Multi-tenancy in Permify refers to an authorization architecture where a single Permify authorization service serves multiple applications/organizations (tenants).

This allows customization of the authorization for each tenant’s specific needs. With Multi-Tenancy support, you can create a custom authorization schema and authorization data for the different tenants and manage them in a single place.

For the users that don’t have/need multi-tenancy in their authorization structure, we created a pre-inserted tenant (id: t1) that comes default when you serve a Permify service.

Tenancy Based APIs

Almost all Permify API endpoints have a ‍tenant_id mandatory field. Let’s examine a check request below,

Check API

cr, err: = client.Permission.Check(context.Background(), & v1.PermissionCheckRequest {
    TenantId: "t1",
    Metadata: & v1.PermissionCheckRequestMetadata {
        SnapToken: ""
        SchemaVersion: ""
        Depth: 20,
    Entity: & v1.Entity {
        Type: "repository",
        Id: "1",
    Permission: "edit",
    Subject: & v1.Subject {
        Type: "user",
        Id: "1",

    if (cr.can === PermissionCheckResponse_Result.RESULT_ALLOWED) {
    } else {
        // RESULT_DENIED

Users that come from version 0.2.x and users that have a single tenant can enter t1 as tenant id. See changes on the other endpoints from API Overview Section.

Tenancy Service

To manage tenants we have added a Tenancy service; you can create, delete and list tenants. See the Tenancy Service in Using The API section.

Permission Database

Tenant Table

A tenants table has been added to the Permissions database to store tenants’ details.

├── migrations       
├── relation_tuples   
├── schema_definitions   
├── tenants   
├── transactions   

Tenant ID Column

Authorization DATA and schema definition tables now have a tenant_id column, which stores the id of the tenant that the data belongs.

Let’s take a look at a snapshot of the demo table on an example Permission Database.

Example Relation Tuples data table: tenant-id-tuples

Example Schema Definitions data table tenant-id-schema

Need any help ?

Our team is happy to help you get started with Permify. If you’d like to learn more about using Permify in your app or have any questions about this example, schedule a call with one of our Permify engineers. Alternatively you can join our discord community to discuss.