OPopal
role-assignments

List role assignments

Changed on

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.

get/role-assignments

Request

  • Base URL
    https://api.opal.dev/v1
  • Auth
    HTTP bearer

Query parameters

entity_idsstring[]

Filter to grants on these entity (resource or group) IDs. Any-match.

principal_idsstring[]

Filter to grants with these principal (user, group, or resource) IDs. Any-match.

entity_type'GROUP' | 'RESOURCE'

Entity type for a role assignment. Entities are the resources or groups access is granted on.

Example:RESOURCE

Filter by entity type. Omit to include both RESOURCE and GROUP entities.

principal_type'GROUP' | 'RESOURCE' | 'USER'

The type of an entity.

Example:GROUP

Filter by principal type. Omit to include USER, GROUP, and RESOURCE principals.

cursorstring

The pagination cursor value.

page_sizeinteger

Number of results to return per page. Default is 200.

Response

Paginated list of role assignments.

nextstring nullable

The cursor with which to continue pagination if additional result pages exist.

previousstring nullable

The cursor used to obtain the current result page.

Example response

{
  "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:00Z"
    }
  ]
}

Changes