> ## 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. # List roles > Returns the built-in roles followed by the organization's custom roles, each tagged `builtIn`. Built-in roles carry their permissions derived from the catalog; Organization admin is published as the `*` action. Filter by `scope`, and by `tenantId` for tenant-scoped custom roles. Page with `cursor` and `perPage`: `perPage` bounds the custom roles, the built-in roles appear on the first page only, and a `cursor` this list did not issue answers 400 `InvalidCursor`. ## OpenAPI ````yaml /api-reference/organization-openapi.yaml get /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: get: tags: - Roles summary: List roles description: > Returns the built-in roles followed by the organization's custom roles, each tagged `builtIn`. Built-in roles carry their permissions derived from the catalog; Organization admin is published as the `*` action. Filter by `scope`, and by `tenantId` for tenant-scoped custom roles. Page with `cursor` and `perPage`: `perPage` bounds the custom roles, the built-in roles appear on the first page only, and a `cursor` this list did not issue answers 400 `InvalidCursor`. operationId: listOrganizationRoles parameters: - in: query name: scope schema: type: string enum: - organization - tenant description: Return only roles of this scope. - in: query name: tenantId schema: type: string format: uuid description: Return only custom roles bound to this tenant. - $ref: '#/components/parameters/cursor' - $ref: '#/components/parameters/perPage' responses: '200': description: Roles, built-in first. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Role' meta: $ref: '#/components/schemas/PageMeta' example: data: - id: f68ed9a1-8eb4-443a-8ceb-203fa3d0bc4e name: Organization admin description: >- Full administration of the organization and every tenant. Superset of Tenant admin. scope: organization permissions: - actions: - '*' builtIn: true - id: 31fd6afb-8d68-495a-98f2-fb0c0e455493 name: Tenant read-only description: Read-only access within assigned tenants scope: tenant permissions: - actions: - Finding:Read - Alert:Read - Asset:Read builtIn: true - id: 3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90 organizationId: 7c9a1b2e-3d4f-4a5b-8c6d-9e0f1a2b3c4d scope: tenant tenantId: 9d0e1f2a-3b4c-4d5e-8f7a-8b9c0d1e2f3a name: Finding triage description: Triage findings on the production accounts permissions: - actions: - Finding:Read - Finding:Triage resources: - e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b - actionGroup: read-only resources: '*' createdAt: '2026-09-10T04:12:00.000Z' updatedAt: '2026-09-15T09:31:00.000Z' createdBy: 60f1a2b3c4d5e6f7a8b9c0d1 updatedBy: 9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f builtIn: false meta: cursor: null '400': $ref: '#/components/responses/ListRolesBadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' components: parameters: cursor: name: cursor in: query required: false description: >- The `meta.cursor` value from the previous page, passed back unchanged. Cursors are opaque and URL-safe. schema: type: string perPage: name: perPage in: query required: false description: Items per page, 1 to 1000. schema: type: string pattern: ^[1-9][0-9]{0,2}$|^1000$ schemas: 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 PageMeta: type: object properties: cursor: type: - string - 'null' description: Pass as `cursor` to fetch the next page. `null` on the last page. required: - cursor 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 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: ListRolesBadRequest: description: > A query parameter is invalid (`InvalidQuery`), or `cursor` is not one this list issued (`InvalidCursor`). content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: InvalidCursor message: >- cursor is not one this list issued; pass meta.cursor from the previous page 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' 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. ````