> ## 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 role assignments > Returns the assignments matching exactly one filter: `roleId`, `userId` or `groupId`. A request with no filter answers 400 `MissingAssignmentFilter`. Page with `cursor` and `perPage`; a `cursor` this list did not issue answers 400 `InvalidCursor`. A `userId` listing also includes the built-in roles the user was granted in the Plerion app, with `createdAt` and `createdBy` null, since those grants carry no date or author. A role held both ways is listed once. ## OpenAPI ````yaml /api-reference/organization-openapi.yaml get /v1/organization/role-assignments 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: get: tags: - Role assignments summary: List role assignments description: > Returns the assignments matching exactly one filter: `roleId`, `userId` or `groupId`. A request with no filter answers 400 `MissingAssignmentFilter`. Page with `cursor` and `perPage`; a `cursor` this list did not issue answers 400 `InvalidCursor`. A `userId` listing also includes the built-in roles the user was granted in the Plerion app, with `createdAt` and `createdBy` null, since those grants carry no date or author. A role held both ways is listed once. operationId: listOrganizationRoleAssignments parameters: - in: query name: roleId schema: type: string format: uuid description: Every principal holding this role. - in: query name: userId schema: type: string format: uuid description: >- Every role this user holds directly. Roles held through a user group are listed under the group. - in: query name: groupId schema: type: string format: uuid description: Every role this user group holds. - $ref: '#/components/parameters/cursor' - $ref: '#/components/parameters/perPage' responses: '200': description: Matching assignments. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/RoleAssignment' meta: $ref: '#/components/schemas/PageMeta' example: data: - principal: type: group id: b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e roleId: 3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90 roleScope: tenant tenantId: 9d0e1f2a-3b4c-4d5e-8f7a-8b9c0d1e2f3a createdAt: '2026-09-16T02:00:00.000Z' createdBy: 9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f - principal: type: user id: a0b1c2d3-e4f5-4a6b-9c8d-9e0f1a2b3c4d roleId: f68ed9a1-8eb4-443a-8ceb-203fa3d0bc4e roleScope: organization tenantId: null createdAt: '2026-08-01T00:00:00.000Z' createdBy: 60f1a2b3c4d5e6f7a8b9c0d1 meta: cursor: null '400': $ref: '#/components/responses/ListRoleAssignmentsBadRequest' '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: RoleAssignment: type: object properties: principal: $ref: '#/components/schemas/Principal' roleId: type: string format: uuid roleScope: type: string enum: - organization - tenant tenantId: type: - string - 'null' description: >- The one tenant the assignment applies to. `null` for an organization-scoped role. createdAt: type: - string - 'null' format: date-time description: Null for a built-in role granted in the Plerion app. createdBy: type: - string - 'null' description: >- The user id, or the organization API key id when created over this API. Null for a built-in role granted in the Plerion app. required: - principal - roleId - roleScope - tenantId - createdAt - createdBy PageMeta: type: object properties: cursor: type: - string - 'null' description: Pass as `cursor` to fetch the next page. `null` on the last page. required: - cursor Principal: type: object properties: type: type: string enum: - user - group id: type: string format: uuid description: The user id or user group id. required: - type - id 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 responses: ListRoleAssignmentsBadRequest: description: > No filter was given (`MissingAssignmentFilter`), 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: MissingAssignmentFilter message: provide userId, groupId or roleId 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. ````