---
title: "List role assignments"
method: GET
path: "/role-assignments"
tags: ["role-assignments"]
---

# List role assignments

`GET /role-assignments`

## Request

- Base URL: `https://api.opal.dev/v1`
- URL: `https://api.opal.dev/v1/role-assignments`
- Auth: HTTP bearer

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.

## Query parameters

- `entity_ids` string[]
- `principal_ids` string[]
- `entity_type` 'GROUP' | 'RESOURCE': Entity type for a role assignment. Entities are the resources or groups access is granted on.
- `principal_type` 'GROUP' | 'RESOURCE' | 'USER': The type of an entity.
- `cursor` string
- `page_size` integer

## Response `200`

Paginated list of role assignments.

- PaginatedRoleAssignmentsList: A paginated page of role assignments.
  - `next` string, nullable: The cursor with which to continue pagination if additional result pages exist.
  - `previous` string, nullable: The cursor used to obtain the current result page.
  - `results` RoleAssignment[], required
    - `id` string, uuid, required: Unique identifier for the role assignment.
    - `entity_id` string, uuid, required: The ID of the entity (resource or group) being accessed.
    - `entity_type` 'GROUP' | 'RESOURCE' | 'USER', required: The type of an entity.
    - `principal_id` string, uuid, required: The ID of the principal being granted access.
    - `principal_type` 'GROUP' | 'RESOURCE' | 'USER', required: The type of an entity.
    - `access_level` ResourceAccessLevel: # 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.
      - `access_level_name` string, required: The human-readable name of the access level.
      - `access_level_remote_id` string, required: The machine-readable identifier of the access level.
    - `expiration` string, date-time, nullable: When this access expires. Null when the grant is indefinite.
    - `granted_at` string, date-time, nullable: When this access was first granted.

## Other responses

- `400`: Invalid query parameter: unknown entity_type / principal_type enum value, malformed UUID, malformed cursor, or page_size outside the allowed range.
- `403`: Caller is not an admin or read-only admin.

## Changes

- **2026-10-22** `8fce5da23873`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/opal/apis/opal-api/changes/role-assignments/get.md)

---

[API](https://skmtc.dev/opal/apis/opal-api.md) - [All operations](https://skmtc.dev/opal/apis/opal-api/llms.txt) - [OpenAPI document](https://skmtc.dev/opal/apis/opal-api/revisions/e7877ea96eab?raw)