> ## Documentation Index > Fetch the complete documentation index at: https://docs.plerion.com/llms.txt > Use this file to discover all available pages before exploring further. # Assign a role > Grants a built-in or custom role to a user or a user group. For the built-in Tenant admin and Tenant read-only roles, `tenantId` names the one tenant the grant applies to and is required; for every other role it is not accepted, because a custom role is already bound to its tenant. A tenant that is not in your organization answers 404 `TenantNotFound`, and a user that does not exist answers 404 `UserNotFound`. Granting the same role to the same principal for the same tenant twice answers 409 `AssignmentAlreadyExists`. Users your identity provider manages over SCIM can be granted roles directly, like any other user. Requires the readWrite access level. ## OpenAPI ````yaml /api-reference/organization-openapi.yaml post /v1/organization/role-assignments openapi: 3.1.0 info: title: Plerion organization API version: v1 termsOfService: https://www.plerion.com/terms-and-conditions contact: name: Plerion Pty Ltd url: https://www.plerion.com/contact-us email: support@plerion.com license: name: Plerion Use License url: https://www.plerion.com/terms-and-conditions description: |- The Plerion organization API manages roles and role assignments for a whole organization: the roles that exist, the permissions each one grants, and which users and user groups hold them. It covers the same lifecycle as the roles and user access pages of the Plerion app, so an automation can grant and revoke access without a person signing in. Requests are authenticated with a Plerion organization API key sent as a bearer token. The organization is resolved from the key, so no request names an organization. Reads work with a key of either access level; writes need a key with the readWrite access level. List responses are `{ "data": [...], "meta": { "cursor": ... } }`. Pass `meta.cursor` back as the `cursor` query parameter to fetch the next page; it is `null` on the last page. Single objects are `{ "data": ... }`. Deletes answer 204 with no body. Errors are `{ "errors": [{ "code": ..., "message": ... }] }`. servers: - url: https://{region}.api.plerion.com description: Production API server - Select your preferred region variables: region: default: au enum: - au - sg1 - in1 - us1 security: - organizationApiKey: [] tags: - name: Roles x-displayName: Roles description: >- Built-in and custom roles. A built-in role's permissions are fixed and shown for reference; a custom role's permissions name actions or action groups from the permission catalog, optionally narrowed to specific integrations. Writes need an organization API key with the readWrite access level. - name: Role assignments x-displayName: Role assignments description: >- Which users and user groups hold which roles. A tenant-scoped role applies to one tenant; an organization-scoped role applies everywhere. Writes need an organization API key with the readWrite access level. - name: Permission catalog x-displayName: Permission catalog description: >- The actions and action groups a role's permissions may name, with the level and resource type of each action. Read this before writing a role. paths: /v1/organization/role-assignments: post: tags: - Role assignments summary: Assign a role description: > Grants a built-in or custom role to a user or a user group. For the built-in Tenant admin and Tenant read-only roles, `tenantId` names the one tenant the grant applies to and is required; for every other role it is not accepted, because a custom role is already bound to its tenant. A tenant that is not in your organization answers 404 `TenantNotFound`, and a user that does not exist answers 404 `UserNotFound`. Granting the same role to the same principal for the same tenant twice answers 409 `AssignmentAlreadyExists`. Users your identity provider manages over SCIM can be granted roles directly, like any other user. Requires the readWrite access level. operationId: createOrganizationRoleAssignment requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateRoleAssignmentRequest' examples: customRoleToGroup: summary: Custom role to a user group value: roleId: 3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90 principal: type: group id: b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e tenantAdminOnOneTenant: summary: Built-in Tenant admin on one tenant value: roleId: b16184ca-b44a-4a0f-b879-95588322ad69 principal: type: user id: a0b1c2d3-e4f5-4a6b-9c8d-9e0f1a2b3c4d tenantId: 9d0e1f2a-3b4c-4d5e-8f7a-8b9c0d1e2f3a responses: '201': description: The created assignment. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/RoleAssignment' '400': $ref: '#/components/responses/CreateRoleAssignmentBadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' components: schemas: CreateRoleAssignmentRequest: type: object properties: roleId: type: string format: uuid principal: $ref: '#/components/schemas/Principal' tenantId: type: string format: uuid description: >- Required for the built-in Tenant admin and Tenant read-only roles, not accepted for any other role. required: - roleId - principal additionalProperties: false RoleAssignment: type: object properties: principal: $ref: '#/components/schemas/Principal' roleId: type: string format: uuid roleScope: type: string enum: - organization - tenant tenantId: type: - string - 'null' description: >- The one tenant the assignment applies to. `null` for an organization-scoped role. createdAt: type: - string - 'null' format: date-time description: Null for a built-in role granted in the Plerion app. createdBy: type: - string - 'null' description: >- The user id, or the organization API key id when created over this API. Null for a built-in role granted in the Plerion app. required: - principal - roleId - roleScope - tenantId - createdAt - createdBy Principal: type: object properties: type: type: string enum: - user - group id: type: string format: uuid description: The user id or user group id. required: - type - id Error: type: object properties: errors: type: array items: type: object properties: code: type: string message: type: string field: type: string description: Present on validation errors. required: - code - message required: - errors responses: CreateRoleAssignmentBadRequest: description: > The body is invalid (`InvalidBody`), `tenantId` is missing for a built-in tenant role (`TenantIdRequired`), given for any other role (`TenantIdNotAllowed`) or `*` (`TenantWildcardNotAllowed`), or the user group does not exist (`GroupNotFound`). content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: TenantIdRequired message: tenantId is required for this role Unauthorized: description: The organization API key is missing, malformed or revoked. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- The key has the read access level and the operation writes, or the key is a tenant API key. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: > No such role, user, tenant, assignment or principal kind. Codes include `RoleNotFound`, `UserNotFound`, `TenantNotFound`, `AssignmentNotFound` and `PrincipalKindNotFound`. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: RoleNotFound message: role not found Conflict: description: > The change conflicts with current state. Codes include `AssignmentAlreadyExists`, `RoleHasAssignments`, `RoleHasApiKeys`, `BreakGlassRolesLocked` and `UserRecordChanged`. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: RoleHasAssignments message: role has active assignments; revoke them first securitySchemes: organizationApiKey: type: http scheme: bearer description: > Plerion organization API key (plerion_oak_…), created by an organization admin in the Plerion app. GET operations work with a key of either access level; POST, PUT and DELETE require the readWrite access level. ````