> ## 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 an organization API key with read and write access. ## 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, role assignments and preferences for a whole organization: the roles that exist, the permissions each one grants, which users and user groups hold them, and the home dashboard and navigation each user or user group gets in a tenant. It covers the same lifecycle as the roles, user access and dashboard assignment pages of the Plerion app, so an automation can grant access and set defaults 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. 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. - 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. - 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. - name: Preferences x-displayName: Preferences description: >- The home dashboard and sidebar navigation a user or a user group gets in one tenant. A user's own setting wins, then the most recently updated of their user groups, then the tenant default (home dashboard only). Each setting is a sub-resource: PUT replaces it, DELETE clears it so the next level applies. 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 an organization API key with read and write access. 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 example: '2026-10-05T04:12:00.000Z' 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.