> ## 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. # Create a custom role > Creates a custom role. `tenantId` is required for a tenant-scoped role and not accepted for an organization-scoped one; a tenant that is not in your organization answers 404 `TenantNotFound`. Each permission names either `actions` or an `actionGroup` from the permission catalog. An action whose `resourceType` is `integration` needs `resources`: `*` for every integration, or a list of integration ids. In an organization-scoped role only `*` is allowed. An action whose `resourceType` is `null` takes no `resources`, and an organization-level action cannot be used in a tenant-scoped role. Requires the readWrite access level. ## OpenAPI ````yaml /api-reference/organization-openapi.yaml post /v1/organization/roles 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: post: tags: - Roles summary: Create a custom role description: > Creates a custom role. `tenantId` is required for a tenant-scoped role and not accepted for an organization-scoped one; a tenant that is not in your organization answers 404 `TenantNotFound`. Each permission names either `actions` or an `actionGroup` from the permission catalog. An action whose `resourceType` is `integration` needs `resources`: `*` for every integration, or a list of integration ids. In an organization-scoped role only `*` is allowed. An action whose `resourceType` is `null` takes no `resources`, and an organization-level action cannot be used in a tenant-scoped role. Requires the readWrite access level. operationId: createOrganizationRole requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateRoleRequest' example: name: Finding triage description: Triage findings on the production accounts scope: tenant tenantId: 9d0e1f2a-3b4c-4d5e-8f7a-8b9c0d1e2f3a permissions: - actions: - Finding:Read - Finding:Triage resources: - e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b responses: '201': description: The created role. content: application/json: schema: $ref: '#/components/schemas/RoleResponse' '400': $ref: '#/components/responses/CreateRoleBadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' components: schemas: CreateRoleRequest: type: object properties: name: type: string minLength: 1 maxLength: 120 description: type: string maxLength: 500 scope: type: string enum: - organization - tenant tenantId: type: string format: uuid description: >- Required for `scope: tenant`, not accepted for `scope: organization`. permissions: type: array minItems: 1 items: $ref: '#/components/schemas/Permission' required: - name - scope - 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: CreateRoleBadRequest: description: > The body is invalid (`InvalidBody`), `tenantId` does not match the scope (`InvalidRoleScope`), or a permission breaks the catalog rules (`InvalidRolePermissions`). content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: InvalidRolePermissions message: >- org-level action 'Organization:Read' cannot be used in a tenant-scoped 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 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. ````