# Tenants From [Descope Enterprise Identity](https://learn.descope.io/c/b2b) — Enterprise SSO, tenant-based identity, and the provisioning patterns that arrive with enterprise customers. Take this course interactively at https://learn.descope.io/c/b2b/tenants --- ![Project-Scoped Identity, Tenant-Scoped Authorization. 5 minutes.](video:tenants-project-identity-tenant-authorization) This is the load-bearing idea in multi-tenancy, so it is worth stating plainly: a user has one login ID, one credential set, and one MFA enrollment across the whole project. What differs per tenant is what they are allowed to do. Identity lives above the tenant; authorization lives inside it. If `alice@company.com` signs up under one tenant and is later added to another, she authenticates with the same password or passkey in both. Descope does not ask her to re-register. What changes is her role — Admin in one, Member in another — and those roles, with the permissions they carry, appear scoped per tenant inside her session token. ## Where the many-tenant case actually shows up - Contractors and consultants working across several of your customers, who need one login rather than one per engagement - Partners and resellers whose staff support multiple customer tenants - Your own support and success staff, who need a role inside customer tenants without becoming customers In every one of these, the alternative is a separate account per tenant: password sprawl, duplicate MFA enrollments, and a support burden every time somebody's access changes. Project-scoped identity avoids all of it. > [!NOTE] > Tenant User Isolation is the deliberate exception. Turn this project setting on and the same login ID becomes a separate identity in each tenant, with independent credentials and MFA state. It exists for cases like a consultant who uses one address at two unrelated customers and genuinely needs two unrelated accounts. Leave it off unless you have that requirement. ## Key terms - Project-scoped identity — a user's login ID, credentials and MFA enrollment, shared across every tenant they belong to. - Tenant-scoped authorization — roles and permissions assigned per tenant, appearing scoped to that tenant in the JWT. - Tenant User Isolation — the project setting making one login ID a separate identity, with independent credentials, per tenant. ## Summary - That identity is project-scoped and authorization is tenant-scoped - That the same person can hold different roles in different tenants from one credential set - Where the many-tenant case really shows up, and what the alternative costs - That Tenant User Isolation is an exception with a narrow reason to exist --- ![Tenant Configuration. 4 minutes.](video:tenants-tenant-configuration) Once you know what a tenant is, the next question is what you actually set on one. A tenant carries its own display name, custom attributes, associated domains and settings, all sitting alongside but separate from the project-level configuration. Every tenant has a display name, unique within the project, and a tenant ID — generated, or supplied by you — which is the identifier you use in API calls and JWT claims. ## Custom attribute types - Text and numeric - Boolean - Single select and multi select - Date, and month-day Custom attributes are not only storage. Once defined, you can surface them in custom claims on the JWT, or load them at runtime to drive product behavior — gating a feature on a tenant's plan without a separate lookup to your own database. Self-provisioning domains connect an email domain to a tenant automatically: associate `acme.com` with the Acme tenant and anyone signing up with a matching address is placed there with no manual assignment. > [!WARNING] > A self-provisioning domain and an SSO domain are different mechanisms solving different problems. One decides which tenant a user joins; the other routes them to an identity provider at login. A tenant can have either, both, or neither, and confusing the two produces a tenant whose users are assigned correctly but cannot sign in, or the reverse. ## Settings a tenant overrides for itself - Whether the tenant is enabled or disabled - Session and refresh token expiration - Inactivity timeout - Whether SSO is enforced These override the project defaults for that tenant only, so one enterprise customer can run a stricter session policy than everybody else without touching anything project-wide. ## Key terms - Display name — the tenant's human-readable name, unique within the project. - Custom attribute — a typed field defined on the Tenants page and attached to a tenant to store product-specific data. - Self-provisioning domain — an email domain associated with a tenant, placing matching users into it at sign-up. - Tenant settings — per-tenant overrides such as token expiration, inactivity timeout, enabled state, and SSO enforcement. ## Summary - What identifies a tenant, and what typed data you can attach to one - That self-provisioning domains assign users, while SSO domains route them - Which settings a tenant can override for itself, and that the rest stay project-wide --- ![Creating and Managing Tenants from the API. 5 minutes.](video:tenants-tenants-from-the-api) The Console's Tenants page is a fine place to explore the model, create a test tenant, or make a one-off change during support work. It is not where production tenant creation should live. ## The core operations - CreateTenant — creates a tenant with a name and, optionally, a specific ID, self-provisioning domains and custom attributes. Omit the ID and Descope generates one and returns it - UpdateTenant and PatchTenant — modify name, domains or attributes. Update treats the fields you pass as a full override; Patch changes only what you specify - ConfigureTenantSettings — sets the tenant-level settings: token expirations, inactivity timeout, enabled state, SSO enforcement - DeleteTenant — irreversible, with a choice of whether to cascade to the tenant's users and access keys - CreateTenantsBatch, UpdateTenantsBatch, DeleteTenantsBatch — the same operations across many tenants at once, for migrations and bulk provisioning All of these authenticate with a Management Key paired with your Project ID, not an end-user session. This is back-office automation, and none of it belongs anywhere a browser can reach. Creating a tenant by hand works, but it does not compose with what onboarding a customer actually means for your product. A real onboarding path creates the tenant, sets its self-provisioning domain, assigns an initial admin role to the signing-up user, and kicks off billing, CRM and a welcome sequence — as one step that either happens or does not. That coordination only lives comfortably in your own backend, or in a Flow, where you control ordering, retries and what happens when one part fails. Supplying your own tenant ID is what makes that safe to retry. A signup handler that times out and runs again can detect an existing tenant rather than quietly creating a second one. ## Key terms - Management Key — a project-level credential, distinct from end-user sessions, authenticating Management API calls. - CreateTenant — the operation creating a tenant, optionally with a caller-supplied ID for idempotent creation. - Batch operation — a call applying a create, update or delete across many tenants at once. - Idempotent creation — supplying your own ID so a retried request finds the existing tenant instead of duplicating it. ## Summary - Which operations cover the tenant lifecycle, and what Update and Patch do differently - That these authenticate with a Management Key and never belong in a browser - Why onboarding coordination pushes tenant creation into your own code - What a caller-supplied ID buys you when a request is retried --- ![What a Tenant Is. 4 minutes.](video:tenants-what-a-tenant-is) In a B2B product your customers are not copies of your application — they are organizations sharing one application. Descope models this directly: a tenant is a customer organization, and a single project can hold many at once. Think of the project as an office building and each tenant as a company renting a floor. Every company shares the elevators, the power and the security desk, and each keeps its own furniture, staff and locked doors. The project holds your authentication methods, your Flows and your global settings. A tenant has its own users, roles, branding and domains — but it does not get its own copy of the project's authentication configuration. ## What that changes about what you build - You integrate Descope into your application once - Onboarding a customer means creating a tenant inside your existing project - It does not mean standing up a new project, and it does not mean forking your authentication code - Tenants share the project's authentication methods, Flow library and JWT signing Because tenants live inside one project, each keeps its own data, users, roles, domains and settings while sharing everything above that line. A project can have no tenants at all — a pure B2C app with no notion of organizations — or host hundreds, one per customer. You do not have to decide upfront, which is what lets a product grow from B2C into B2B, or from a single enterprise customer into dozens, without restructuring. ## Key terms - Tenant — a customer organization inside a Descope project, with its own users, roles, domains and settings. - Project — the container for your application: authentication methods, Flows, and the global settings every tenant shares. - Multi-tenancy — one application instance serving multiple isolated customer organizations from shared infrastructure. ## Summary - That a tenant represents a customer organization, not a separate deployment - That one project holds zero, one, or many, and tenants can be added at any time - What is shared upward to the project, and what stays inside the tenant ---