Filter users with the API
List the users of an environment and filter them by email, key, name, tenant, or role with the List Users API. This page is for developers who look up users from scripts or backend code.
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 |
tenant_id | Your tenant ID or key (tenant requests only) |
API_SECRET_KEY | Your environment API key |
User filter parameters
| Query parameter | Endpoint | Description |
|---|---|---|
search | Users | Text search on the user email, key, first name, and last name |
search | Tenant users | Text search on the user email |
role | Both | Returns users with the role. Send an empty string to get users without roles. |
page | Both | Page number, starting at 1 |
per_page | Both | Results per page, up to 100 |
List all users
Send a GET request to /v2/facts/{project_id}/{env_id}/users:
curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/users?page=1&per_page=10' \
-H 'authorization: Bearer API_SECRET_KEY'
The API responds with a paginated result. The data array holds the user objects, and total_count and page_count describe the pages:
{
"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
}
Filter users by email, key, and name
Pass the search query parameter. The following request searches for key@permit.io:
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 users that match the search:
{
"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
}
Filter users by tenant
Send the request to the tenant users endpoint, /v2/facts/{project_id}/{env_id}/tenants/tenant_id/users, and replace tenant_id in the path with the tenant ID or key. The API returns only users that have roles in that tenant. To find the tenant key, open the Tenants screen in the Permit dashboard.
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 users of the tenant that match the search:
{
"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
}
Filter users by role
Pass the role query parameter with a role key. The role parameter works on both the users endpoint and the tenant users endpoint. In the following block, the commented-out request shows the tenant users endpoint, and the active request uses the users endpoint:
#curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/tenants/tenant_id/users?search=key@permit.io&role=board&page=1&per_page=3' \
# -H 'authorization: Bearer API_SECRET_KEY'
curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/users?search=key@permit.io&role=board&page=1&per_page=3' \
-H 'authorization: Bearer API_SECRET_KEY'
The API responds with the users that have the board role and match the search:
{
"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
}
Verify the filter
Each user in the data array matches the filters you passed. For example, with role=board, every user lists board in roles. When no user matches, data is empty and total_count is 0.