---
title: Tenancy Customization
project: Authaz
updated: 2026-05-07T23:22:34.913Z
---


# 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 Authaz Sign-In. |
| **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 Authaz Sign-In, 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.