Create a tenant with the API
Create a tenant and list the tenants of an environment with the Permit API. This page is for developers who create tenants from scripts or backend code.
A tenant groups users and their role assignments. A user can have different roles in different tenants. The most common tenant is a customer organization or company. For the concept, see Multi-tenant authorization.
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 |
API_SECRET_KEY | Your environment API key |
Create a tenant
Send a POST request to the Create Tenant API with the tenant fields in the body.
| Field | Required | Description |
|---|---|---|
key | Yes | Unique, URL-friendly identifier of the tenant. Letters, digits, -, and _. |
name | Yes | Display name of the tenant |
description | No | Longer description of the tenant |
attributes | No | Tenant attributes for attribute-based access control (ABAC) policies |
curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/tenants' \
-H 'authorization: Bearer API_SECRET_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{"key":"new-tenant-name","name":"New Tenant Name","description":"New tenant description"}'
The API responds with the created tenant object:
{
"key": "new-tenant-name",
"id": "1e17ad4486cb4320bba067b2f19exxxx",
"organization_id": "903ebc2765b848289d6dfbd3c21exxxx",
"project_id": "3c4244c7bcab4c97990e5bc724daxxxx",
"environment_id": "9ba956da646948538efaee4cf10dxxxx",
"created_at": "2023-07-31T08:16:03+00:00",
"updated_at": "2023-07-31T08:16:03+00:00",
"last_action_at": "2023-07-31T08:16:03+00:00",
"name": "New Tenant Name",
"description": "New tenant description",
"attributes": null
}
List all tenants
Send a GET request to the List Tenants API.
| Query parameter | Description |
|---|---|
search | Text search on the tenant name or key |
include_total_count | When true, the response includes total_count and page_count |
page | Page number, starting at 1 |
per_page | Results per page, up to 100 |
The following request searches for tenants that match default:
curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/tenants?search=default&include_total_count=true&page=1&per_page=100' \
-H 'authorization: Bearer API_SECRET_KEY'
The API responds with the matching tenants:
{
"data": [
{
"key": "default",
"id": "5620130cc6a74ada9f0c194cab20a53e",
"organization_id": "903ebc2765b848289d6dfbd3c21exxxx",
"project_id": "3c4244c7bcab4c97990e5bc724daxxxx",
"environment_id": "9ba956da646948538efaee4cf10dxxxx",
"created_at": "2023-02-28T10:07:44+00:00",
"updated_at": "2023-02-28T10:07:44+00:00",
"last_action_at": "2023-02-28T10:07:44+00:00",
"name": "Default Tenant",
"description": null,
"attributes": null
}
],
"total_count": 1,
"page_count": 1
}
Verify the tenant
Run the list request with search set to the key of the tenant you created. The data array contains the tenant.