Multi-Tenant Authorization

Learn how Permit.io models tenants, so you can isolate each customer's users and resources in a shared application. This page is for developers who add authorization to a multi-tenant service.

What is multi-tenant authorization?

Multi-tenant authorization lets every service in your application serve multiple customers without a separate deployment for each customer. For background, read multitenancy in the cloud on the Permit blog.

Multi-tenancy gives you:

• Access separation between customers, enforced by policy.
• Multiple customers on shared infrastructure and shared services.
• Load balancing and scaling across that shared infrastructure.

An authorization layer lets you move from a single-tenant to a multi-tenant application. One policy applies tenant separation across all relevant services, so each service doesn't implement tenant checks of its own.

Tenants in Permit.io

Tenants are a first-class object in Permit.io: you manage them in the Permit UI, the SDKs, and the API. A tenant usually represents one of your customers. Several tenants can also represent one logical customer, for example one tenant per department.

Tenants belong to an environment. See Projects and environments for the Permit hierarchy.

Tenants as silos of resources and users

A tenant is a silo of resources and users. In policy terms, only users in a tenant can act on the resources in that tenant. Tenants are isolated from one another.

Tenants are data, not policy

In Permit, tenants belong to the facts (data) layer. You can assign users to tenants, but you can't define a different policy for each tenant's roles.

To isolate role schemas per tenant, use separate projects and environments, or filter tenant roles by role attributes through the API.

Assign users to tenants

A user belongs to a tenant through a role assignment in that tenant. For example, user alice has role admin in tenant my-customer. The same user can hold roles in several tenants in the same environment.

Assign roles with the assign role API endpoint, an SDK, or the Directory screen. See Sync users for each method.

Pass the tenant in a permission check

To mark a resource as belonging to a tenant, pass the tenant key in the resource object when you call permit.check(). The Node.js example below passes tenantKey, and every Permit SDK accepts the same tenant field:

const permitted = await permit.check(userKey, "create", {
  type: "document", // The resource name
  tenant: tenantKey, // The tenant key
});

The PDP evaluates the check against the user's roles in the tenantKey tenant. A role the user holds in a different tenant doesn't grant access to resources in tenantKey.

Resource types belong to an environment, not to a tenant. Resource instances belong to a tenant.

Tenant APIs

Task	API reference
Create, list, update, and delete tenants	Tenants API
Assign a user to a tenant through a role	Role Assignments API

Tenants in the Permit UI

Manage tenants and their users in the Directory screen. Select a tenant to see its users, or select All Tenants to see users across tenants.

Next steps

• Sync users: create users and assign them roles in a tenant.
• Check permissions: call permit.check() with a tenant.
• Check permissions across all tenants: find every tenant where a user is allowed an action.
• Projects and environments: when to separate policy by project or environment instead of by tenant.