> ## 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. # Update a custom role > Replaces the name, description and permissions of a custom role. The scope and tenant cannot change. The permission rules are the same as for creating a role. A built-in role answers 400 `BuiltinRoleImmutable`. Users and API keys holding the role receive the new permissions within their token lifetime. Requires the readWrite access level. ## OpenAPI ````yaml /api-reference/organization-openapi.yaml put /v1/organization/roles/{roleId} 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/roles/{roleId}: parameters: - $ref: '#/components/parameters/roleId' put: tags: - Roles summary: Update a custom role description: > Replaces the name, description and permissions of a custom role. The scope and tenant cannot change. The permission rules are the same as for creating a role. A built-in role answers 400 `BuiltinRoleImmutable`. Users and API keys holding the role receive the new permissions within their token lifetime. Requires the readWrite access level. operationId: updateOrganizationRole requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateRoleRequest' example: name: Finding triage description: Triage and dismiss findings on the production accounts permissions: - actions: - Finding:Read - Finding:Triage resources: - e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b - actionGroup: read-only resources: '*' responses: '200': description: The updated role. content: application/json: schema: $ref: '#/components/schemas/RoleResponse' '400': $ref: '#/components/responses/UpdateRoleBadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' components: parameters: roleId: name: roleId in: path required: true description: The role id, built-in or custom. schema: type: string format: uuid schemas: UpdateRoleRequest: type: object properties: name: type: string minLength: 1 maxLength: 120 description: type: string maxLength: 500 permissions: type: array minItems: 1 items: $ref: '#/components/schemas/Permission' required: - name - permissions additionalProperties: false RoleResponse: type: object properties: data: $ref: '#/components/schemas/Role' Permission: description: > One permission: either `actions` or an `actionGroup`, optionally narrowed with `resources`. `resources` is `*` for every integration or a list of integration ids, and is required for actions whose `resourceType` is `integration` and not accepted otherwise. oneOf: - type: object properties: actions: type: array minItems: 1 items: type: string description: Action ids from the permission catalog. resources: $ref: '#/components/schemas/Resources' required: - actions additionalProperties: false - type: object properties: actionGroup: type: string description: An action group id from the permission catalog. resources: $ref: '#/components/schemas/Resources' required: - actionGroup additionalProperties: false Role: type: object properties: id: type: string format: uuid name: type: string description: type: string scope: type: string enum: - organization - tenant permissions: type: array items: $ref: '#/components/schemas/Permission' description: >- For a built-in role, derived from the catalog. Organization admin is the single `*` action. builtIn: type: boolean description: Built-in roles cannot be edited or deleted. organizationId: type: string format: uuid description: Custom roles only. tenantId: type: string format: uuid description: Custom tenant-scoped roles only. createdAt: type: string format: date-time description: Custom roles only. updatedAt: type: string format: date-time description: Custom roles only. createdBy: type: string description: >- Custom roles only. The user id, or the organization API key id when created over this API. updatedBy: type: string description: >- Custom roles only. The user id, or the organization API key id when updated over this API. required: - id - name - scope - permissions - builtIn 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 Resources: description: '`*` for every integration, or a list of integration ids.' oneOf: - type: string const: '*' - type: array minItems: 1 items: type: string responses: UpdateRoleBadRequest: description: > The body is invalid (`InvalidBody`), a permission breaks the catalog rules (`InvalidRolePermissions`), or the role is built in (`BuiltinRoleImmutable`). content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: BuiltinRoleImmutable message: built-in roles cannot be modified 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 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. ````