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
}