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