Skip to main content
Version: 2.0.0

Overview

Retrieve users that exist inside a specific environment and filter them by email, key, tenant or role.

Check the API documentation for more information.

Get All Users

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}/users?page=1&per_page=10' \
-H 'authorization: Bearer API_SECRET_KEY'

The return user object will look like this:

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

Note the search query parameter in the following command.

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

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

Note the tenant_id parameter in the following command. :::

You will only get back users that have roles in the tenant with the tenant_id or the tenant_key you can get the tenant key in this page.

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

{
"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": "test@gmail.com",
"first_name": "",
"last_name": "",
"attributes": {}
}
],
"total_count": 1,
"page_count": 1
}

Filter Users by Role

You can use role_id or role_key to filter users by role.
This filter will also work for the user tenant 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 return user object will look like this:

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