---
title: "Assign role to user"
method: POST
path: "/zones/{zoneId}/users/{userId}/roles"
tags: ["Zone Roles"]
---

# Assign role to user

`POST /zones/{zoneId}/users/{userId}/roles`

Assigns a role to the user. Provide exactly one of role_id or role_identifier; when role_identifier is used, owner_type is required to disambiguate roles that share an identifier across owner types (and must be omitted with role_id). An optional (scope_type, scope_id) pair scopes the grant; only platform roles on the org zone may carry a scope, and a `zone` scope must reference a different zone in the same organization.

## Path parameters

- `zoneId` string, required
- `userId` string, required

## Request body

- IamRoleAssignmentCreate — Schema for assigning a role to a user. Provide exactly one of role_id or role_identifier. When role_identifier is used, owner_type is required to disambiguate roles that share an identifier across owner types; owner_type must be omitted when role_id is used.
  - `role_id` string — ID of the role to assign. Provide exactly one of role_id or role_identifier; owner_type must be omitted when role_id is used.
  - `role_identifier` string — Opaque role identifier. Treated as an opaque identifier by the API and unique within a zone.
  - `owner_type` 'platform' | 'customer' — Owner type of the role to assign. Required with role_identifier (an identifier is unique only per owner type); must be omitted with role_id.
  - `scope_type` string — The kind of resource to scope the grant to (e.g. `zone`). Provide together with scope_id, or omit both for an unscoped assignment (applies to the owning zone itself). Only platform roles on the org zone may carry a scope.
  - `scope_id` string — The ID of the resource to scope the grant to. Provide together with scope_type, or omit both for an unscoped assignment. When scope_type is `zone`, this must reference a different zone in the same organization.

## Response `201`

Represents a role assigned to a user within a zone

- IamRoleAssignment — Represents a role assigned to a user within a zone
  - `id` string, required — Unique identifier of the role assignment
  - `zone_id` string, required — Zone this assignment belongs to
  - `principal_type` string, required — The kind of principal the role is assigned to (e.g. `user`). Always `user` today.
  - `principal_id` string, required — ID of the principal the role is assigned to (e.g. a user ID).
  - `role_id` string, required — ID of the assigned role
  - `role_identifier` string, required — Opaque role identifier. Treated as an opaque identifier by the API and unique within a zone.
  - `scope_type` string, nullable — The kind of resource this grant is scoped to (e.g. `zone`). Null when the assignment is unscoped (applies to the owning zone itself).
  - `scope_id` string, nullable — The ID of the scoped resource. Null when the assignment is unscoped.
  - `created_at` string, date-time, required — Entity creation timestamp
  - `updated_at` string, date-time, required — Entity update timestamp

## Other responses

- `default` — Error response

---

[API](https://skmtc.net/keycardai/apis/untitled-api.md) · [All operations](https://skmtc.net/keycardai/apis/untitled-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/keycardai/untitled-api/versions/2f5033ed4491/schema)