Overview

Retrieve role associations that exist inside a specific environment, filtering for specific user, tenant, role, resource or resource instance.

Check the API documentation for more information.

List Tenant Roles Filter by Role Attributes

The List Roles API allows filtering roles, based on role attributes using the attr_ prefix. This feature enables you to retrieve only the roles matching specific attribute values.

Example

Filter roles by attributes (in this example "color" and "access_level") in your project, by sending a GET request with the following format:

curl 'https://api.permit.io/v2/{project}/{resource}/roles/?attr_color=red&attr_access_level=high' \
  -H 'authorization: Bearer API_SECRET_KEY'

Query Parameters:

• attr_color=red - Filters roles where the attribute color is set to red.
• attr_access_level=high - Filters roles where the attribute access_level is set to high.

The attr_ prefix is used to identify query parameters as attribute filters. You can use multiple attributes to narrow down your search further. In this example, only roles that have both the color set to red and the access_level set to high will be returned in the response.

This is useful when you need to filter roles based on custom attributes that your organization has defined, such as access levels, department names, or any other specific characteristics.

List Role Assignments

First of all we need to get our API_SECRET_KEY from the dashboard and get the current project_id and env_id
Replace API_SECRET_KEY with the key from the Permit dashboard along with the project_id and env_id you got from the API in the following command.

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 return object will look like this:

[
  {
    "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"
  }
]

Filter by User / Tenant

You can use the user or tenant query parameter to filter the role associations by user or 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 return object will look like this:

[
    {
        "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"
    }
]

You can also filter by multiple users or tenants at once.

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

You can use the role query parameter to filter the role associations by role. Note that you can filter for multiple roles at once.

curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/role_assignments?role=admin&role=editor' \
  -H 'authorization: Bearer API_SECRET_KEY'

The return object will look like this:

[
    {
        "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

You can use the resource_instance query parameter to filter resource role associations for a resource 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 return user object will look like this:

[
    {
        "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"
    }
]

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.

You can also filter by resource to get all role associations for a specific resource type.

curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/role_assignments?resource=document' \
  -H 'authorization: Bearer API_SECRET_KEY'

The return object will look like this:

[
    {
        "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"
    }
]