---
title: Tenancy Customization
project: Authaz
updated: 2026-04-29T17:34:59.130Z
---


# Tenancy Customization

Every multi-tenant application answers the same question for each feature: **does every tenant share the application's setting, or does each tenant set its own?**

The **Tenant Customization** section under *Application → Settings → General* is where you make those decisions. Four switches:

```
┌──────────────────────────────┬──────────────────────┐
│ Branding                     │ Application │ Tenant │
│ Email Templates              │ Application │ Tenant │
│ Email Provider               │ Application │ Tenant │
│ Isolated Auth Stack          │   Shared    │ Isolated │
└──────────────────────────────┴──────────────────────┘
```

The first three are simple "shared vs per-tenant" toggles. The fourth is a deeper architectural decision — it controls whether tenants share one user pool and one auth surface, or get fully separate ones.

## Where it lives

**Dashboard → Application → Settings → General → Tenant Customization.** The section only appears for multi-tenant applications. Single-tenant apps don't show it (there's nothing to scope).

## The "Application vs Per Tenant" pattern

Each scope toggle has two values:

- **Application** *(default)* — there is one configuration for the whole application. Every tenant inherits it. The dashboard's Branding / Communications pages don't show a tenant picker; they edit the shared config.
- **Per Tenant** — each tenant has its own configuration. The dashboard adds a tenant picker at the top of the relevant page; switching tenants shows that tenant's overrides (or the inherited application defaults if the tenant hasn't customized).

Switching from Application to Per Tenant doesn't break anything: every tenant starts inheriting the application defaults until you (or the tenant's admin) explicitly overrides. Switching back from Per Tenant to Application reverts every tenant to the application config — *existing overrides are kept in storage but hidden* until you flip back.

## Branding

| Scope | What happens |
|-------|-------------|
| **Application** | One Branding page. Logo, colors, fonts apply to every tenant's Universal Login. |
| **Per Tenant** | Tenant picker on the Branding page. Each tenant can have its own logo, colors, layout. |

Choose **Per Tenant** when:

- Each tenant signs in at their own subdomain (`acme.yourapp.com`, `initech.yourapp.com`) and expects branded login.
- You sell a white-label tier where customers want their own logo on the login page.
- Tenants need to honor their own corporate brand guidelines.

Choose **Application** when:

- Login is consistently your brand across every tenant.
- You don't have the support bandwidth to help tenants pick colors that meet contrast requirements.

API:

```bash
curl -X PATCH https://your-app.authaz.io/api/v1/applications/{appId} \
  -H "X-API-Key: $AUTHAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tenancyConfig": { "brandingScope": "tenant" } }'
```

See the [Branding](./branding.md) page for the per-mode controls available once tenants can customize.

## Email Templates

| Scope | What happens |
|-------|-------------|
| **Application** | One set of 12 templates for the whole application. |
| **Per Tenant** | Each tenant can override individual templates. Templates not overridden fall back to the application defaults. |

Choose **Per Tenant** when:

- Tenants want emails that match their brand voice (formal Acme Inc. copy vs casual Beta Co. copy).
- Different tenants are in different languages and you want per-locale subjects/bodies.
- Specific tenants ask for "Sent on behalf of [their name]" instead of yours.

Choose **Application** when:

- One transactional voice for the whole product.
- You don't want tenant admins editing copy that could mistakenly reveal sensitive info or break links.

```bash
curl -X PATCH https://your-app.authaz.io/api/v1/applications/{appId} \
  -H "X-API-Key: $AUTHAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tenancyConfig": { "emailTemplatesScope": "tenant" } }'
```

See [Communications & Email Templates](./communications.md) for the full template list and editor.

## Email Provider

| Scope | What happens |
|-------|-------------|
| **Application** | All transactional emails go through the same provider account (your Resend key, your sending domain). |
| **Per Tenant** | Each tenant can plug in their own provider — their own Resend account, their own `From` domain. |

Choose **Per Tenant** when:

- Customers insist email comes from `notifications@theircompany.com`, not yours.
- A tenant has compliance requirements that mandate emails from their own infrastructure.
- Different tenants are large enough to warrant separate sending reputations.

Choose **Application** when:

- Centralized deliverability is more important than per-tenant branding of the sender.
- Smaller tenants don't have someone to manage Resend keys.

This setting is independent of `emailTemplatesScope`. A common combination: **Per-Tenant Templates** (each tenant edits copy) but **Application Provider** (you handle deliverability for everyone).

```bash
curl -X PATCH https://your-app.authaz.io/api/v1/applications/{appId} \
  -H "X-API-Key: $AUTHAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tenancyConfig": { "emailProviderScope": "tenant" } }'
```

## Isolated Auth Stack

This is the architectural decision. The other three are "can a tenant override this UI"; this one is "is the entire authentication system per-tenant or shared."

| Mode | Effect |
|------|--------|
| **Shared** *(default)* | One auth surface for every tenant. Users log in at the same Universal Login, the application's auth providers (Password, Google, SAML, …) apply to all tenants, password policy and MFA enforcement are application-wide. Users can hop between tenants with the same identity. |
| **Isolated** | Each tenant has its own auth providers, password policy, MFA, custom domain. A user signs in at their tenant's surface and exists only there. Cross-tenant identity is impossible. |

The toggle in the UI is a switch with on-screen labels — "Isolated" or "Shared" — and flipping it to Isolated requires explicit confirmation. Flipping back to Shared saves directly, but the API rejects with `409 Conflict` if any tenant still has tenant-specific auth data that would be left orphaned (you'll need to remove tenant-scoped providers, custom domains, etc., first).

### When to pick Isolated

- **Compliance-driven multi-tenancy** — healthcare, finance, government tenants must not share an auth surface with anyone else.
- **Reseller / white-label** — each tenant is effectively a separate product with its own login.
- **Enterprise customers with their own SAML IdP** *and* their own MFA policy *and* their own password rules — at some point it's just a separate auth stack.
- **Large tenants with custom domains** — `auth.acme.com`, `auth.initech.com` — that need entirely separate provider configs.

### When to pick Shared

- **Self-service B2B** — many small tenants, none of them care about the auth surface, you want one place to administer everything.
- **Cross-workspace identity** — your product expects users to belong to multiple tenants without re-signing-up.
- **Single sign-on across tenants** — a user who's an admin of two tenants sees one login and a tenant picker.

### What "Isolated" actually changes in the dashboard

When auth isolation is **Shared**:

- Authentication tab shows app-level config for every provider.
- Password policy, MFA settings, OAuth providers, magic-link config — all application-wide.
- The Communications and Branding tabs follow their *own* scope toggles independently.

When auth isolation flips to **Isolated**:

- Authentication tab gains a tenant picker at the top.
- Every provider (Password, Magic Link, OAuth, Passkey, SAML, M2M, API Keys) can be configured per tenant.
- Tenant-specific custom domains become editable on the Domains page.
- The application-level provider config becomes the *fallback* for tenants without overrides — useful so new tenants don't start blank.

### API

```bash
# Switch on isolated auth (will warn in the UI)
curl -X PATCH https://your-app.authaz.io/api/v1/applications/{appId} \
  -H "X-API-Key: $AUTHAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tenancyConfig": { "authIsolation": "isolated" } }'

# Switch back to shared (rejects 409 if cleanup needed)
curl -X PATCH https://your-app.authaz.io/api/v1/applications/{appId} \
  -H "X-API-Key: $AUTHAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tenancyConfig": { "authIsolation": "shared" } }'
```

## How tenant overrides look in the dashboard

When a feature is set to **Per Tenant** and you visit its page:

- A **tenant picker** appears at the top.
- Each tenant card / row shows an **Inherited** badge (using application defaults) or **Customized** badge (this tenant has its own overrides).
- A **Remove tenant override** button on the editor restores inheritance — useful for resetting a tenant that drifted.

The whole UX is "edit by exception" — you only override the tenants that need to differ from the default.

## Putting it together

A typical configuration matrix:

| Use case | Branding | Templates | Provider | Auth |
|----------|---------:|---------:|--------:|-----:|
| **B2B SaaS, your-brand login for everyone** | App | App | App | Shared |
| **B2B SaaS, white-label for top tier customers** | Tenant | Tenant | App | Shared |
| **Reseller platform** | Tenant | Tenant | Tenant | Isolated |
| **Healthcare with strict tenant separation** | Tenant | Tenant | Tenant | Isolated |
| **Internal tool with one auth surface** | App | App | App | Shared |

Every cell can be flipped later, with the small caveat noted under "Isolated Auth Stack" — flipping Isolated → Shared requires cleaning tenant-specific auth data first.

## Practical tips

- **Default to Application.** Start every multi-tenant app with all four switches on the application side. Add per-tenant scope only when you have a concrete tenant asking.
- **Branding is the most-asked-for first override.** When you need *any* per-tenant feature, it's usually branding. Communications is a close second.
- **Auth Isolation is a bigger leap than the other three combined.** Treat it like a small architectural migration, not a checkbox flip.
- **Document who can edit overrides.** When you allow per-tenant customization, decide whether *you* (the platform admin) or *the tenant admin* can edit them. Authaz's role system lets you scope this, but the policy decision is yours.

## Next steps

- [Multi-tenancy](./multi-tenancy.md) — single, shared-pool, and isolated-pool tenancy models.
- [Branding](./branding.md) — what's editable when branding is per-tenant.
- [Communications & Email Templates](./communications.md) — what's editable when emails are per-tenant.
- [Application Settings](./application-settings.md) — where the Tenant Customization section lives.