> ## 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. # Revoke a role > Removes one assignment. For the built-in Tenant admin and Tenant read-only roles, the `tenantId` query parameter names which tenant's grant to revoke and is required; for every other role it is not accepted. For a user and a built-in role, the grant is removed wherever it is held, including one made in the Plerion app, in the one call. Answers 404 `AssignmentNotFound` when the principal does not hold the role, and 409 `UserRecordChanged` when the user was edited at the same moment; retry. Requires the readWrite access level. ## OpenAPI ````yaml /api-reference/organization-openapi.yaml delete /v1/organization/role-assignments/{roleId}/{principalType}/{principalId} 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/{roleId}/{principalType}/{principalId}: parameters: - $ref: '#/components/parameters/roleId' - name: principalType in: path required: true description: '`users` or `groups`.' schema: type: string enum: - users - groups - name: principalId in: path required: true description: The user id or user group id. schema: type: string format: uuid delete: tags: - Role assignments summary: Revoke a role description: > Removes one assignment. For the built-in Tenant admin and Tenant read-only roles, the `tenantId` query parameter names which tenant's grant to revoke and is required; for every other role it is not accepted. For a user and a built-in role, the grant is removed wherever it is held, including one made in the Plerion app, in the one call. Answers 404 `AssignmentNotFound` when the principal does not hold the role, and 409 `UserRecordChanged` when the user was edited at the same moment; retry. Requires the readWrite access level. operationId: deleteOrganizationRoleAssignment parameters: - in: query name: tenantId schema: type: string format: uuid description: The tenant of the grant to revoke. Built-in tenant roles only. responses: '204': description: Revoked. '400': $ref: '#/components/responses/DeleteRoleAssignmentBadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' components: parameters: roleId: name: roleId in: path required: true description: The role id, built-in or custom. schema: type: string format: uuid responses: DeleteRoleAssignmentBadRequest: description: > `tenantId` is missing for a built-in tenant role (`TenantIdRequired`), given for any other role (`TenantIdNotAllowed`) or `*` (`TenantWildcardNotAllowed`). content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: TenantWildcardNotAllowed message: tenantId must name one tenant; "*" is not accepted on this API 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 schemas: 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 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. ````