---
title: "List Role Assignments"
method: GET
path: "/v2/facts/{proj_id}/{env_id}/role_assignments"
tags: ["Role Assignments"]
---

# List Role Assignments

`GET /v2/facts/{proj_id}/{env_id}/role_assignments`

## Request

- Base URL: `https://api.permit.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.permit.io/v2/facts/{proj_id}/{env_id}/role_assignments`
- Auth: HTTP bearer

Lists the role assignments defined within an environment.

- If the `user` filter is present, will only return the role assignments of that user (supports multiple).
- If the `tenant` filter is present, will only return the role assignments in that tenant (supports multiple).
- If the `role` filter is present, will only return role assignments that are granting that role (supports multiple).
- If the `resource` filter is present, will only return role assignments for resource instances of that resource type.
- If the `resource_instance` filter is present, will only return role assignments for that resource instance.

Providing both `tenant` and `resource_instance` filters will only return role assignments if the resource instance is in that tenant.
If multiple tenants are received, the last tenant will be compared with the resource instance.

## Path parameters

- `proj_id` string, required: Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").
- `env_id` string, required: Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").

## Query parameters

- `user` string[]: optional user(s) filter, will only return role assignments granted to this user(s). Split larger sets into successive requests of at most 100 values each.
- `role` string[]: optional role(s) filter, will only return role assignments granting this role(s). Split larger sets into successive requests of at most 100 values each.
- `tenant` string[]: optional tenant(s) filter, will only return role assignments granted in that tenant(s). Split larger sets into successive requests of at most 100 values each. Note: when combined with `resource_instance`, only the **last** tenant value is used to resolve that instance, while the tenant filter itself still applies to every value. If the instance exists under that last tenant, the result is skewed by that resolution; if it does not, the request fails with **404** even when the instance exists under another tenant in the list. Either outcome depends on the order of the values, so pass a single tenant alongside `resource_instance`.
- `resource` string: optional resource **type** filter, will only return role assignments granted on that resource type.
- `resource_instance` string: optional resource instance filter, will only return role assignments granted on that resource instance.
- `detailed` boolean: Whether to return full details about the user, tenant and role
- `include_total_count` boolean: If true, returns the list of role assignments and the total count.
- `page` integer: Page number of the results to fetch, starting at 1.
- `per_page` integer: The number of results per page (max 1000).

## Response `200`

Successful Response

- union
  - RoleAssignmentRead[]
    - `id` string, uuid, required: Unique id of the role assignment
    - `user` string, required: the user the role is assigned to
    - `role` string, required: the role that is assigned
    - `tenant` string: the tenant the role is associated with
    - `resource_instance` string: the resource instance the role is associated with
    - `resource_instance_id` string, uuid: Unique id of the resource instance
    - `user_id` string, uuid, required: Unique id of the user
    - `role_id` string, uuid, required: Unique id of the role
    - `tenant_id` string, uuid, required: Unique id of the tenant
    - `organization_id` string, uuid, required: Unique id of the organization that the role assignment belongs to.
    - `project_id` string, uuid, required: Unique id of the project that the role assignment belongs to.
    - `environment_id` string, uuid, required: Unique id of the environment that the role assignment belongs to.
    - `created_at` string, date-time, required: Date and time when the role assignment was created (ISO_8601 format).
  - PaginatedResultRoleAssignmentRead
    - `data` RoleAssignmentRead[], required: List of Role Assignments
      - `id` string, uuid, required: Unique id of the role assignment
      - `user` string, required: the user the role is assigned to
      - `role` string, required: the role that is assigned
      - `tenant` string: the tenant the role is associated with
      - `resource_instance` string: the resource instance the role is associated with
      - `resource_instance_id` string, uuid: Unique id of the resource instance
      - `user_id` string, uuid, required: Unique id of the user
      - `role_id` string, uuid, required: Unique id of the role
      - `tenant_id` string, uuid, required: Unique id of the tenant
      - `organization_id` string, uuid, required: Unique id of the organization that the role assignment belongs to.
      - `project_id` string, uuid, required: Unique id of the project that the role assignment belongs to.
      - `environment_id` string, uuid, required: Unique id of the environment that the role assignment belongs to.
      - `created_at` string, date-time, required: Date and time when the role assignment was created (ISO_8601 format).
    - `total_count` integer, required
    - `page_count` integer
  - RoleAssignmentDetailedRead[]
    - `id` string, uuid, required: Unique id of the role assignment
    - `role` RoleAssignmentRole, required
      - `id` string, uuid, required
      - `key` string, required
      - `name` string, required
      - `permissions` string[]
    - `user` RoleAssignmentUser, required
      - `id` string, uuid, required
      - `key` string, required
      - `email` string
      - `first_name` string
      - `last_name` string
      - `attributes` object
    - `tenant` RoleAssignmentTenant, required
      - `id` string, uuid, required
      - `key` string, required
      - `name` string, required
      - `attributes` object
    - `resource_instance` RoleAssignmentResourceInstance
      - `id` string, uuid, required
      - `key` string, required
      - `resource` string, required
      - `attributes` object
    - `organization_id` string, uuid, required: Unique id of the organization that the role assignment belongs to.
    - `project_id` string, uuid, required: Unique id of the project that the role assignment belongs to.
    - `environment_id` string, uuid, required: Unique id of the environment that the role assignment belongs to.
    - `created_at` string, date-time, required: Date and time when the role assignment was created (ISO_8601 format).
  - PaginatedResultRoleAssignmentDetailedRead
    - `data` RoleAssignmentDetailedRead[], required: List of Role Assignment Detaileds
      - `id` string, uuid, required: Unique id of the role assignment
      - `role` RoleAssignmentRole, required
        - `id` string, uuid, required
        - `key` string, required
        - `name` string, required
        - `permissions` string[]
      - `user` RoleAssignmentUser, required
        - `id` string, uuid, required
        - `key` string, required
        - `email` string
        - `first_name` string
        - `last_name` string
        - `attributes` object
      - `tenant` RoleAssignmentTenant, required
        - `id` string, uuid, required
        - `key` string, required
        - `name` string, required
        - `attributes` object
      - `resource_instance` RoleAssignmentResourceInstance
        - `id` string, uuid, required
        - `key` string, required
        - `resource` string, required
        - `attributes` object
      - `organization_id` string, uuid, required: Unique id of the organization that the role assignment belongs to.
      - `project_id` string, uuid, required: Unique id of the project that the role assignment belongs to.
      - `environment_id` string, uuid, required: Unique id of the environment that the role assignment belongs to.
      - `created_at` string, date-time, required: Date and time when the role assignment was created (ISO_8601 format).
    - `total_count` integer, required
    - `page_count` integer

## Other responses

- `422`: Validation Error

## Changes

- **2026-05-15** `6a33af02350c`: 1 info
  - for the `query` request parameter `per_page`, the max was increased from `100.00` to `1000.00`
- **2025-09-16** `05b99f06db87`: 2 info
  - `query` request parameter `detailed` was deprecated
  - `query` request parameter `include_total_count` was deprecated

[Operation history](https://skmtc.dev/permit/apis/permit-io-api/changes/v2/facts/:proj_id/:env_id/role_assignments/get.md)

---

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