List the role permissions of a user with the API
List the permissions a user gets from top-level roles with the Permit API: get the roles of the user, then get the permissions of each role. This page is for developers who build admin tools or reports from the Permit API.
The API method on this page reads stored role assignments and role definitions. The method does not evaluate resource instance roles, derived roles from relationship-based access control (ReBAC), or attribute-based access control (ABAC) conditions. To get the effective permissions of a user for a permission-aware UI or data filtering, call permit.getUserPermissions() on the policy decision point (PDP).
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} | Your project ID or key |
{env_id} | Your environment ID or key |
user_id_or_key | The user ID or key |
tenant_id | The tenant ID or key. If you don't use tenants, use default. |
role_id_or_key | A role ID or key from the user object, such as admin or board |
API_SECRET_KEY | Your environment API key |
1. Get the roles of the user
Get the user object with the Get User API. The roles array of the user object lists each role and the tenant the role applies in.
Get the user by ID or key
Send a GET request to https://api.permit.io/v2/facts/{project_id}/{env_id}/users/user_id_or_key with the API key in the authorization header:
curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/users/user_id_or_key' \
-H 'authorization: Bearer API_SECRET_KEY'
The API responds with the user object:
{
"key": "key@permit.io",
"id": "d084172f638140e7a90622ff8311xxx",
"organization_id": "903ebc2765b848289d6dfbd3c21exxxx",
"project_id": "3c4244c7bcab4c97990e5bc724daxxxx",
"environment_id": "9ba956da646948538efaee4cf10dxxxx",
"associated_tenants": [
{
"tenant": "default",
"roles": [
"board",
"test",
"admin"
],
"status": "active"
}
],
"roles": [
{
"role": "board",
"tenant": "default"
},
{
"role": "test",
"tenant": "default"
},
{
"role": "admin",
"tenant": "default"
}
],
"email": "key@permit.io",
"first_name": "",
"last_name": "",
"attributes": {}
}
Search users by key or email
If you don't know the exact user key, search the users of the environment with the search query parameter:
curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/users?search=key@permit.io&page=1&per_page=3' \
-H 'authorization: Bearer API_SECRET_KEY'
The API responds with the matching users, each with a roles array:
{
"data": [
{
"key": "key@permit.io",
"id": "445ed9ff1bc94caf8bcf686ea3eexxxx",
"organization_id": "903ebc2765b848289d6dfbd3c21exxxx",
"project_id": "3c4244c7bcab4c97990e5bc724daxxxx",
"environment_id": "9ba956da646948538efaee4cf10dxxxx",
"associated_tenants": [
{
"tenant": "sample_tenant",
"roles": [
"board"
],
"status": "active"
}
],
"roles": [
{
"role": "board",
"tenant": "sample_tenant"
}
],
"email": "email@permit.io",
"first_name": "",
"last_name": "",
"attributes": null
}
],
"total_count": 1,
"page_count": 1
}
Search the users of a tenant
To get only the users that have roles in one tenant, search the tenant users endpoint:
curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/tenants/tenant_id/users?search=key@permit.io&page=1&per_page=3' \
-H 'authorization: Bearer API_SECRET_KEY'
The API responds with the matching users of the tenant:
{
"data": [
{
"key": "key@permit.io",
"id": "d084172f638140e7a90622ff8311xxx",
"organization_id": "903ebc2765b848289d6dfbd3c21exxxx",
"project_id": "3c4244c7bcab4c97990e5bc724daxxxx",
"environment_id": "9ba956da646948538efaee4cf10dxxxx",
"associated_tenants": [
{
"tenant": "default",
"roles": [
"board",
"test",
"admin"
],
"status": "active"
}
],
"roles": [
{
"role": "board",
"tenant": "default"
},
{
"role": "test",
"tenant": "default"
},
{
"role": "admin",
"tenant": "default"
}
],
"email": "key@permit.io",
"first_name": "",
"last_name": "",
"attributes": {}
}
],
"total_count": 1,
"page_count": 1
}
2. Get the permissions of each role
A user can have several roles. For each role in the roles array of the user, get the role with the Get Role API:
curl 'https://api.permit.io/v2/schema/{project_id}/{env_id}/roles/role_id_or_key' \
-H 'authorization: Bearer API_SECRET_KEY'
The API responds with the role object. The permissions array lists the permissions of the role in the resource:action format. The extends array lists the keys of roles that this role inherits all permissions from. Get each extended role the same way.
{
"name": "board",
"description": "",
"permissions": [
"user:delete",
"document:create",
"file:create",
"user:read",
"user:login",
"file:read",
"user:update",
"user:get",
"user:create"
],
"attributes": null,
"extends": [],
"granted_to": null,
"key": "board",
"id": "d611591f8f51421aa6877e2aeb6909a8",
"organization_id": "903ebc2765b848289d6dfbd3c21e392b",
"project_id": "3c4244c7bcab4c97990e5bc724dafe85",
"environment_id": "9ba956da646948538efaee4cf10d1815",
"created_at": "2023-03-09T12:33:18+00:00",
"updated_at": "2023-03-09T12:33:18+00:00"
}
3. Combine the permissions
Merge the permissions arrays of all the roles of the user, including the extended roles, and remove duplicates. The result is the list of permissions the user has from top-level roles. For example, a user with the board role in the preceding response can create a document, because the list contains document:create.
Roles apply per tenant. If the user has roles in several tenants, combine the permissions per tenant.