Filter role assignments with the API
List the role assignments of an environment and filter them by user, tenant, role, resource type, or resource instance with the List Role Assignments API. This page is for developers who audit or debug who has which role from scripts or backend code. The last section shows how to filter roles, instead of role assignments, by role attributes.
A role assignment (also called a role association) grants a role to a user in a tenant, or on a specific resource instance.
Prerequisites
- An environment API key (Get your API key)
- The project ID or key and the environment ID or key (Get the project ID and environment ID)
In each request on this page, replace:
| Placeholder | Value |
|---|---|
{project_id} or {project} | Your project ID or key |
{env_id} or {environment} | Your environment ID or key |
API_SECRET_KEY | Your environment API key |
List role assignments
Send a GET request to /v2/facts/{project_id}/{env_id}/role_assignments. Use page (starting at 1) and per_page (up to 1000) to page through the results.
curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/role_assignments?page=1&per_page=10' \
-H 'authorization: Bearer API_SECRET_KEY'
The API responds with an array of role assignment objects. A resource_instance of null means the role applies across the tenant (a top-level role).
[
{
"id": "0e82b2e3d2ed42c1ae0c525256b052f0",
"user": "charlie",
"role": "admin",
"tenant": "default",
"resource_instance": null,
"resource_instance_id": null,
"user_id": "9012410ede514dbe854e51f70f79014e",
"role_id": "c9fe4928753f48d79124bedfc760b14d",
"tenant_id": "8d15d835c04c40429807215e9aee418e",
"organization_id": "47b37e40e1094a2580fc6589ad24fec5",
"project_id": "6b84d0a6705c4c81a8818f4e7bb0f589",
"environment_id": "47e86c08899f4b798657fd19f09b54c1",
"created_at": "2024-06-30T21:29:52+00:00"
}
]
Role assignment filter parameters
| Query parameter | Accepts | Multiple values |
|---|---|---|
user | User key | Yes, up to 100 per request |
tenant | Tenant key | Yes, up to 100 per request |
role | Role key | Yes, up to 100 per request |
resource | Resource type key, such as document | No |
resource_instance | Resource instance, such as document:photo | No |
detailed | true returns full details of the user, tenant, and role | No |
To pass multiple values, repeat the parameter: user=alice&user=bob. Filters of different parameters combine with a logical AND.
Filter by user or tenant
Use the user and tenant query parameters. The following request returns the role assignments of bob in the default tenant:
curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/role_assignments?user=bob&tenant=default' \
-H 'authorization: Bearer API_SECRET_KEY'
The API responds with the matching role assignments:
[
{
"id": "25e7915145334ca7815de96a65335902",
"user": "bob",
"role": "editor",
"tenant": "default",
"resource_instance": null,
"resource_instance_id": null,
"user_id": "c428e65465f94eea888ac274d2a428a5",
"role_id": "8aef7d34bab64ddea739fd30f10d3e37",
"tenant_id": "8d15d835c04c40429807215e9aee418e",
"organization_id": "47b37e40e1094a2580fc6589ad24fec5",
"project_id": "6b84d0a6705c4c81a8818f4e7bb0f589",
"environment_id": "47e86c08899f4b798657fd19f09b54c1",
"created_at": "2024-06-30T21:30:11+00:00"
}
]
The following request returns the role assignments of alice and bob in the default tenant:
curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/role_assignments?user=alice&user=bob&tenant=default' \
-H 'authorization: Bearer API_SECRET_KEY'
Filter by role
Use the role query parameter. The following request returns the assignments of the admin and editor roles:
curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/role_assignments?role=admin&role=editor' \
-H 'authorization: Bearer API_SECRET_KEY'
The API responds with the matching role assignments:
[
{
"id": "0e82b2e3d2ed42c1ae0c525256b052f0",
"user": "charlie",
"role": "admin",
"tenant": "default",
"resource_instance": null,
"resource_instance_id": null,
"user_id": "9012410ede514dbe854e51f70f79014e",
"role_id": "c9fe4928753f48d79124bedfc760b14d",
"tenant_id": "8d15d835c04c40429807215e9aee418e",
"organization_id": "47b37e40e1094a2580fc6589ad24fec5",
"project_id": "6b84d0a6705c4c81a8818f4e7bb0f589",
"environment_id": "47e86c08899f4b798657fd19f09b54c1",
"created_at": "2024-06-30T21:29:52+00:00"
},
{
"id": "25e7915145334ca7815de96a65335902",
"user": "bob",
"role": "editor",
"tenant": "default",
"resource_instance": null,
"resource_instance_id": null,
"user_id": "c428e65465f94eea888ac274d2a428a5",
"role_id": "8aef7d34bab64ddea739fd30f10d3e37",
"tenant_id": "8d15d835c04c40429807215e9aee418e",
"organization_id": "47b37e40e1094a2580fc6589ad24fec5",
"project_id": "6b84d0a6705c4c81a8818f4e7bb0f589",
"environment_id": "47e86c08899f4b798657fd19f09b54c1",
"created_at": "2024-06-30T21:30:11+00:00"
}
]
Filter by resource instance
Use the resource_instance query parameter, in the format resource_type:instance_key. The following request returns the role assignments on the document:photo instance:
curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/role_assignments?resource_instance=document:photo' \
-H 'authorization: Bearer API_SECRET_KEY'
The API responds with the role assignments on that instance:
[
{
"id": "f7bbee0360494e96ba9bf594e807b040",
"user": "alice",
"role": "owner",
"tenant": "default",
"resource_instance": "document:photo",
"resource_instance_id": "560bd95aa9a94032a74541f6c55a883f",
"user_id": "9b14f8deb1274af09931c2cfb3cb4cf8",
"role_id": "b4f9cb32df60459291a00ca5be7c1bb9",
"tenant_id": "8d15d835c04c40429807215e9aee418e",
"organization_id": "47b37e40e1094a2580fc6589ad24fec5",
"project_id": "6b84d0a6705c4c81a8818f4e7bb0f589",
"environment_id": "47e86c08899f4b798657fd19f09b54c1",
"created_at": "2024-06-30T22:36:44+00:00"
}
]
When you pass several tenant values together with resource_instance, the API uses only the last tenant value to resolve the resource instance. If the instance is not in that last tenant, the request fails with a 404 error, even when the instance exists in another tenant in the list. Pass a single tenant value together with resource_instance.
Filter by resource type
Use the resource query parameter to get the role assignments on all instances of a resource type. The following request returns the role assignments on every document instance:
curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/role_assignments?resource=document' \
-H 'authorization: Bearer API_SECRET_KEY'
The API responds with the role assignments on document instances:
[
{
"id": "94fc60c369cb4c5da6f2e497a29eca9f",
"user": "bob",
"role": "owner",
"tenant": "default",
"resource_instance": "document:spreadsheet",
"resource_instance_id": "33234730008f4bbab25b208c62cfb169",
"user_id": "c428e65465f94eea888ac274d2a428a5",
"role_id": "b4f9cb32df60459291a00ca5be7c1bb9",
"tenant_id": "8d15d835c04c40429807215e9aee418e",
"organization_id": "47b37e40e1094a2580fc6589ad24fec5",
"project_id": "6b84d0a6705c4c81a8818f4e7bb0f589",
"environment_id": "47e86c08899f4b798657fd19f09b54c1",
"created_at": "2024-06-30T22:37:58+00:00"
},
{
"id": "f7bbee0360494e96ba9bf594e807b040",
"user": "alice",
"role": "owner",
"tenant": "default",
"resource_instance": "document:photo",
"resource_instance_id": "560bd95aa9a94032a74541f6c55a883f",
"user_id": "9b14f8deb1274af09931c2cfb3cb4cf8",
"role_id": "b4f9cb32df60459291a00ca5be7c1bb9",
"tenant_id": "8d15d835c04c40429807215e9aee418e",
"organization_id": "47b37e40e1094a2580fc6589ad24fec5",
"project_id": "6b84d0a6705c4c81a8818f4e7bb0f589",
"environment_id": "47e86c08899f4b798657fd19f09b54c1",
"created_at": "2024-06-30T22:36:44+00:00"
}
]
Verify the filter
Each role assignment in a filtered response matches every filter you passed. For example, with role=admin&role=editor, every object has "role": "admin" or "role": "editor". An empty array means no role assignment matches the filters.
Filter roles by role attributes
To filter roles, instead of role assignments, use the List Roles API with query parameters that start with attr_. Each attr_<attribute>=<value> parameter matches roles whose attribute equals the value. Only the equals comparison is supported. To define role attributes, see Define role attributes.
The following request returns the roles whose color attribute is red and whose access_level attribute is high:
curl 'https://api.permit.io/v2/schema/{project}/{environment}/roles?attr_color=red&attr_access_level=high' \
-H 'authorization: Bearer API_SECRET_KEY'
| Query parameter | Matches roles where |
|---|---|
attr_color=red | The color attribute is red |
attr_access_level=high | The access_level attribute is high |
When you pass several attr_ parameters, the API returns only the roles that match all of them. Use role attributes to tag roles by custom characteristics, such as access level or department, and to separate the roles that belong to each tenant.