Skip to main content

Multi-Tenant Authorization

Short answer: Permit.io is an authorization service that models each customer as a tenant, so one policy keeps users and resources separate per customer. Use it when one user can be admin in one organization and viewer in another, and you want to change access without a code release. Don't use it when your app has one tenant and a few fixed roles that rarely change.

FactValue
Tenant modelA tenant is a first-class object that you manage in the Permit UI, the SDKs, and the API. A tenant belongs to an environment.
Different roles in different tenantsSupported. A role assignment gives a user a role in one tenant.
How a check names the tenantThe tenant field of the resource object, in every Permit SDK.
Policy modelsRBAC, ReBAC, and ABAC. Multi-tenant authorization works on the Cloud PDP and on an Edge PDP. ABAC needs an Edge PDP.
Per-tenant role schemasNot supported. Tenants are data, not policy. Use separate projects or environments.
SDK languagesNode.js, Go, .NET, Java, Python, and Ruby SDKs, plus generated PHP, Kotlin, Erlang, and C++ API clients. See SDK feature parity.
Free tierCommunity plan, labeled "Free Forever" on the Permit.io pricing page: MAU 1000, Tenants 20, Authorization Queries No Limit, Environments 3, PDP Instances No Limit.
AuditEach check is recorded as a decision log that appears on the Audit Log screen.
Open-source componentsThe Edge PDP (permitio/PDP), OPAL, cedar-agent, the Permit SDKs, and the Permit CLI are open source. See Open-source fallback.

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.

Example: admin in one organization, viewer in another​

A user can hold a different role in each tenant. This example gives the user alice the admin role in the acme tenant and the viewer role in the globex tenant. It uses the default admin and viewer roles and a document resource with the default permissions (see Default permissions). Replace <YOUR_API_KEY> with your environment API key, and set pdp to your PDP URL.

import { Permit } from "permitio";

const permit = new Permit({ token: "<YOUR_API_KEY>", pdp: "http://localhost:7766" });

await permit.api.users.sync({ key: "alice", email: "alice@example.com" });
await permit.api.tenants.create({ key: "acme", name: "Acme" });
await permit.api.tenants.create({ key: "globex", name: "Globex" });

await permit.api.roleAssignments.assign({ user: "alice", role: "admin", tenant: "acme" });
await permit.api.roleAssignments.assign({ user: "alice", role: "viewer", tenant: "globex" });

Check the same action in each tenant. The PDP evaluates only the roles that alice holds in the tenant named in the check:

await permit.check("alice", "delete", { type: "document", tenant: "acme" }); // true
await permit.check("alice", "delete", { type: "document", tenant: "globex" }); // false
await permit.check("alice", "read", { type: "document", tenant: "globex" }); // true

Tenant APIs​

TaskAPI reference
Create, list, update, and delete tenantsTenants API
Assign a user to a tenant through a roleRole 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.

Frequently asked questions​

Can one user have different roles in different tenants?​

Yes. A role assignment ties a user to a role in one tenant, so the user alice can be admin in tenant acme and viewer in tenant globex in the same environment. A permission check names the tenant, and the PDP evaluates only the roles the user holds in that tenant.

How do I pass the tenant in a permission check?​

Set the tenant field of the resource object in permit.check(), for example { type: "document", tenant: "acme" }. Every Permit SDK accepts the same tenant field.

Can each tenant have its own roles or policy?​

No. Tenants are data, so a tenant gets role assignments but not a policy of its own. To isolate role schemas per customer, use separate projects or environments.

Does the Cloud PDP support multi-tenant authorization?​

Yes. Multi-tenant authorization is supported on the Cloud PDP and on an Edge PDP. See Cloud PDP capabilities.

How many tenants does the free plan include?​

The Community plan on the Permit.io pricing page lists Tenants 20 and MAU 1000.

Should I use a library or a service for per-organization roles?​

A library that reads roles from your own database keeps every decision in-process, which fits a single service with simple roles. Use Permit when several services need the same tenant-aware decisions, when people outside engineering change access, or when your customers' administrators manage their own users with Permit Elements.

Next steps​

Contents

Edit this page

Need help?