Organisation, tenant, application

IntelliAuth structures the world in three layers, top to bottom: organisation → tenant → application. Once you have the right mental model for what sits where, the rest of the docs make sense without effort. This page is the small upfront investment.

The three layers (and a fourth)

Organisation              ← your company, the IntelliAuth customer
   └── Tenant             ← a sub-environment within your company (business unit, product line, env)
         └── Application  ← an actual app or API registered under the tenant
               └── Identity ← the end-user signing into the application

Organisation — your company

The organisation is you. When your company signs up to IntelliAuth, you create an organisation. There's one organisation per IntelliAuth customer. Examples:

A company called Cymmetri signs up → "Cymmetri" is one organisation in IntelliAuth.
A solo developer prototyping a side project → still one organisation (just one human running it).

The organisation is the billing entity, the audit boundary, and the parent of every tenant your company runs. As a developer integrating IntelliAuth, you usually don't talk to the organisation layer directly — your code talks to tenants. But it's the layer that contains everything you do.

Tenant — a sub-environment within your organisation

A tenant is one isolated environment under your organisation. Each tenant has its own users, applications, sessions, MFA configuration, branding, and audit log — entirely separate from every other tenant in the same organisation.

Tenants are your sub-units, not your customers. What you put in a tenant depends on how you've sliced your business:

By product line. Cymmetri's banking product gets cymmetri-banking. Their healthcare product gets cymmetri-health. Two tenants, one organisation. Users of the banking product can't see (and aren't visible to) users of the healthcare product.
By environment. cymmetri-staging for pre-prod testing; cymmetri-prod for production. Same product, different environments. Tenants are cheap; this is fine.
By region. cymmetri-eu and cymmetri-us for data-residency-driven separation.
By customer cohort (rare). If your business genuinely needs hard isolation between two slices of your customers (regulatory, contractual), per-cohort tenants work — but consider whether the application + identity layers can give you the separation you need without spinning a tenant per group.

The tenant URL pattern is fixed: https://<tenant-slug>-<org-slug>.<domain>. So under the Cymmetri organisation, a tenant slug banking gives end-users a sign-in URL like https://banking-cymmetri.intelliauth.local. Your SDK is configured with this URL.

Application — your code, registered under a tenant

An application is a specific integration — your web app, your mobile app, your backend API, your admin tool. Each gets registered under a tenant with its own client id, redirect URIs, scopes, and token lifetimes. See Applications and clients.

A single tenant typically has multiple applications:

cymmetri-banking tenant has applications for: banking web app, banking iOS app, banking Android app, banking-API (M2M), banking-admin-tool.

Each of those applications talks to the same tenant (same users, same MFA, same branding) but is a separate registration.

Identity — the end-user

Identities are the actual humans signing into your applications. They live inside tenants — one identity per email per tenant. If alice@example.com signs into the cymmetri-banking tenant, IntelliAuth creates one identity for her under that tenant. If she also signs into cymmetri-health (a separate tenant under the same org), that's a separate identity — same email, different tenant, different user. Tenants don't share identities.

How the SDK fits

Your SDK instance is configured with the tenant URL plus one application's client id:

<IntelliAuthProvider
  tenantUrl="https://banking-cymmetri.intelliauth.local"
  clientId="app_01HZX..."  // ← the banking web app's client id
  redirectUri={`${window.location.origin}/callback`}
>

The SDK talks to that one tenant. Multiple frontends under the same tenant each register their own application (different clientId) but point at the same tenantUrl. Multiple frontends under different tenants need separate SDK instances entirely.

What lives at each layer

A quick cheat sheet for "where does X get configured?":

Concept	Layer
Billing, plan tier	Organisation
Members operating IntelliAuth (your platform team)	Organisation
Org-level audit log	Organisation
End-users (identities)	Tenant
Authentication policy (allowed methods, MFA enforcement)	Tenant
MFA enrolments	Tenant (per identity)
Branding (logo, colours, email templates)	Tenant
Applications + their client secrets	Tenant
Token lifetimes, scope allowlist	Application
Redirect URIs	Application
Per-tenant audit log (sign-ins, MFA challenges, password changes)	Tenant

If you're not sure where a setting lives, the layer above is rarely the answer — when in doubt, the tenant is the most common location.