> ## 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. Requires an organization API key with read access. ## 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, 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/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. Requires an organization API key with read access. 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.