> ## Documentation Index > Fetch the complete documentation index at: https://docs.opal.dev/llms.txt > Use this file to discover all available pages before exploring further. # List role assignments > Returns a paginated list of role assignments. This endpoint is **admin-only**: the caller's bearer token must belong to a user with the admin or read-only admin role. Non-admin callers receive 403. Mirrors the GraphQL `directRoleAssignments` query and shares the same underlying code path, so pagination order, sort default (`first_granted_at` DESC), and the set of grants returned are identical across the two surfaces. The REST filter surface is intentionally narrower on first ship — sort, risk-factor filters, text search, access-scope filters, the agents/humans toggle, and access-level filtering are deferred to a future revision. For a single entity/principal pair, the per-pair endpoints — `/resources/{resource_id}/users`, `/resources/{resource_id}/groups`, `/resources/{resource_id}/non-human-identities`, `/groups/{group_id}/users`, `/groups/{group_id}/containing-groups` — are often simpler. ## OpenAPI ````yaml https://app.opal.dev/openapi.yaml get /role-assignments openapi: 3.1.0 info: contact: email: hello@opal.dev name: Opal Team url: https://www.opal.dev/ description: >- The Opal API is a RESTful API that allows you to interact with the Opal Security platform programmatically. title: Opal API version: '1.0' servers: - description: Production url: https://api.opal.dev/v1 security: [] tags: - name: access-rules description: Operations related to access rules - name: agent-activity description: Operations related to agent activity telemetry - name: apps description: Operations related to apps - name: bundles description: Operations related to bundles - name: campaigns description: Operations related to access review campaigns - name: configuration-templates description: Operations related to configuration templates - name: delegations description: Operations related to request reviewer delegations - name: event-streams description: Operations related to event streaming connections - name: events description: Operations related to events - name: groups description: Operations related to groups - name: group-bindings description: Operations related to group bindings - name: idp-group-mappings description: Operations related to IDP group mappings - name: message-channels description: Operations related to message channels - name: non-human-identities description: Operations related to non-human identities - name: on-call-schedules description: Operations related to on-call schedules - name: opal-queries description: Operations related to OpalQuery - name: opal-scripts description: Operations related to OpalScripts - name: owners description: Operations related to owners - name: requests description: Operations related to requests - name: resources description: Operations related to resources - name: role-assignments description: >- Operations related to role assignments (general grants between an entity and a principal) - name: paladin description: Operations related to Paladin - name: sessions description: Operations related to sessions - name: tags description: Operations related to tags - name: tokens description: Operations related to API tokens - name: uars description: Operations related to UARs. Deprecated in favor of the `campaigns` API. - name: users description: Operations related to users paths: /role-assignments: get: tags: - role-assignments summary: List role assignments description: | Returns a paginated list of role assignments. This endpoint is **admin-only**: the caller's bearer token must belong to a user with the admin or read-only admin role. Non-admin callers receive 403. Mirrors the GraphQL `directRoleAssignments` query and shares the same underlying code path, so pagination order, sort default (`first_granted_at` DESC), and the set of grants returned are identical across the two surfaces. The REST filter surface is intentionally narrower on first ship — sort, risk-factor filters, text search, access-scope filters, the agents/humans toggle, and access-level filtering are deferred to a future revision. For a single entity/principal pair, the per-pair endpoints — `/resources/{resource_id}/users`, `/resources/{resource_id}/groups`, `/resources/{resource_id}/non-human-identities`, `/groups/{group_id}/users`, `/groups/{group_id}/containing-groups` — are often simpler. operationId: listRoleAssignments parameters: - description: Filter to grants on these entity (resource or group) IDs. Any-match. explode: true in: query name: entity_ids required: false schema: items: type: string format: uuid type: array style: form - description: >- Filter to grants with these principal (user, group, or resource) IDs. Any-match. explode: true in: query name: principal_ids required: false schema: items: type: string format: uuid type: array style: form - description: >- Filter by entity type. Omit to include both RESOURCE and GROUP entities. explode: true in: query name: entity_type required: false schema: $ref: '#/components/schemas/RoleAssignmentEntityTypeEnum' style: form - description: >- Filter by principal type. Omit to include USER, GROUP, and RESOURCE principals. explode: true in: query name: principal_type required: false schema: $ref: '#/components/schemas/EntityTypeEnum' style: form - description: The pagination cursor value. example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw explode: true in: query name: cursor required: false schema: type: string style: form - description: Number of results to return per page. Default is 200. example: 200 explode: true in: query name: page_size required: false schema: type: integer maximum: 1000 style: form responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedRoleAssignmentsList' description: Paginated list of role assignments. '400': description: | Invalid query parameter: unknown entity_type / principal_type enum value, malformed UUID, malformed cursor, or page_size outside the allowed range. '403': description: Caller is not an admin or read-only admin. security: - BearerAuth: [] components: schemas: RoleAssignmentEntityTypeEnum: description: >- Entity type for a role assignment. Entities are the resources or groups access is granted on. enum: - GROUP - RESOURCE example: RESOURCE type: string EntityTypeEnum: description: The type of an entity. enum: - GROUP - RESOURCE - USER example: GROUP type: string PaginatedRoleAssignmentsList: description: A paginated page of role assignments. example: next: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw previous: cj1sZXdwd2VycWVtY29zZnNkc2NzUWxNMEUxTXk0ME16UXpNallsTWtJ results: - id: 29827fb8-f2dd-4e80-9576-28e31e9934ac entity_id: 1b978423-db0a-4037-a4cf-f79c60cb67b3 entity_type: RESOURCE principal_id: e8581682-04f7-473a-a419-472f0fb26d46 principal_type: USER granted_at: '2024-07-10T19:21:00.000Z' properties: next: description: >- The cursor with which to continue pagination if additional result pages exist. example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw nullable: true type: string previous: description: The cursor used to obtain the current result page. example: cj1sZXdwd2VycWVtY29zZnNkc2NzUWxNMEUxTXk0ME16UXpNallsTWtJ nullable: true type: string results: items: $ref: '#/components/schemas/RoleAssignment' type: array type: object required: - results RoleAssignment: description: >- A role assignment representing access granted to a principal for an entity. type: object required: - id - entity_id - entity_type - principal_id - principal_type properties: id: description: Unique identifier for the role assignment. format: uuid type: string entity_id: description: The ID of the entity (resource or group) being accessed. format: uuid type: string entity_type: $ref: '#/components/schemas/EntityTypeEnum' principal_id: description: The ID of the principal being granted access. format: uuid type: string principal_type: $ref: '#/components/schemas/EntityTypeEnum' access_level: description: >- The level of access granted. Null when the entity does not define access levels. allOf: - $ref: '#/components/schemas/ResourceAccessLevel' nullable: true expiration: description: When this access expires. Null when the grant is indefinite. format: date-time nullable: true type: string granted_at: description: When this access was first granted. format: date-time nullable: true type: string ResourceAccessLevel: description: >- # Access Level Object ### Description The `AccessLevel` object is used to represent the level of access that a principal has. The "default" access level is a `AccessLevel` object whose fields are all empty strings. ### Usage Example View the `AccessLevel` of a resource/user or resource/group pair to see the level of access granted to the resource. example: access_level_name: AdminRole access_level_remote_id: arn:aws:iam::590304332660:role/AdministratorAccess properties: access_level_name: description: The human-readable name of the access level. example: AdminRole type: string access_level_remote_id: description: The machine-readable identifier of the access level. example: arn:aws:iam::590304332660:role/AdministratorAccess type: string required: - access_level_name - access_level_remote_id type: object securitySchemes: BearerAuth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.