Platform

Tenant setup

Tenants are the primary isolation boundary in Authalla. They determine which users exist, which authentication options are available, and which domains/endpoints your apps use.

What a tenant means for your customers

A tenant owns (and isolates) your:

  • User identity: a user’s identity is scoped to a single tenant and is not shared across tenants. For end users, this means accounts and login history are separate between tenants even if the same email is used.
  • Login experience: enabled auth methods, branding/theme, email sender, and SSO connections decide what end users see.
  • OAuth2/OIDC integration: apps are created per tenant, and tokens include the tenant context (for example the tid claim). See Sessions & tokens.
  • Tenant domain: your issuer (iss), discovery URL, and OAuth2 endpoints are tenant-domain scoped (default {tenant-id}.authalla.com, or your custom domain). See Custom domains.

If you have an Authalla account, you already have a default tenant. You can find the tenant id in the Admin UI under Tenants → (select tenant) (it appears as the monospaced id in the header). A new tenant's id is three words, such as brave-otter-lantern, so its default domain is brave-otter-lantern.authalla.com. When you create a tenant in the Admin UI, you pick its id from a few suggestions; press Show other IDs for more. Tenants created before October 2026 keep their original id. The id can't be changed; to give users a branded address, set up a custom domain.

Most teams should start with one tenant per environment:

  • Development
  • Staging
  • Production

Each environment's app lives in its tenant and lists only that environment's redirect URIs. The environments can be subdomains of one domain or on different domains altogether. See Environments for worked examples, local development and preview deployments.

Additional tenants are useful when you need strong isolation for configuration or user identity, for example:

  • Multiple products / brands: separate branding, email sender, and login policy.
  • Regions / data residency: distinct tenant domains and configuration per region.
  • Different auth policies: e.g. one tenant in “forced SSO mode” (enterprise SSO only), another allowing passkeys + magic links.

Avoid using a tenant per your customer organization unless you truly need hard isolation. It increases operational overhead (more config to manage, more drift, and more integration points to keep in sync). Authalla does not currently provide strong built-in support for this pattern; if you adopt it, expect custom development on your side and limited platform tooling to help manage it.

Tenant domains, issuer, and endpoints

Every tenant has a base URL:

  • Default: https://{tenant-id}.authalla.com
  • Custom domain (optional): https://auth.yourcompany.com (see Custom domains)

From the base URL you get the most important endpoints:

https://{tenant-domain}/.well-known/openid-configuration
https://{tenant-domain}/oauth2/authorize
https://{tenant-domain}/oauth2/token
https://{tenant-domain}/oauth2/userinfo

If you enable a custom domain, the issuer (iss) changes to that domain for tokens minted on that host. Browsers also treat sessions as host-scoped, so users may need to sign in again when switching between default and custom domains. Details are in Custom domains.

Most important tenant settings (Admin UI)

In the Admin UI, open Tenants → (select tenant). The settings below map to the tenant tabs.

General

  • Allow user registration (allow_registration): If enabled, new users can sign up in this tenant. If disabled, users must already exist (or arrive through SSO or an organization's SCIM provisioning) to sign in. On for a new tenant unless you create it with allow_registration: false.

  • Allow AI agents and MCP clients (allow_client_id_metadata_documents): If enabled, MCP clients and other agents that identify themselves with a Client ID Metadata Document (Claude Code, Claude Desktop and other MCP clients) can sign users of this tenant in. They always go through a consent screen. Off by default; see OAuth2 & OIDC.

  • Sign-in methods (auth_methods): The ways to sign in that Authalla provides itself:

    • magic_link: Magic link / PIN code (email)
    • passkeys: Passkeys (WebAuthn)

    Social and enterprise sign-in are not sign-in methods: they work while the tenant has an enabled connection (see Connections below). The list can be empty, for example to make users of an enterprise connection's domains sign in only through their company's identity provider. The tab warns when a tenant has no sign-in method and no enabled connection, because nobody could sign in.

  • Token lifetimes: Per-tenant access token, ID token, and refresh token TTLs. Defaults and guidance are in Sessions & tokens. Changes apply to newly issued tokens.

  • Allowed origins (CORS): the web origins allowed to call this tenant from a browser — the OAuth2 endpoints and the Application API. Browser-based apps (SPAs) need their origin here. Include the protocol, for example https://app.example.com or http://localhost:3000. Backend-to-backend calls do not use CORS. Unlike the settings above, each add or remove saves immediately. A tenant that has never had allowed origins allows the origins of its apps' redirect URIs instead; once it has one, only its allowed origins are. Removing the last one here leaves no browser able to call the tenant until one is added. A deployment pipeline can add and remove them too: see Allowed origins from a deployment pipeline.

Connections

Add, enable and edit the tenant's social, enterprise OIDC and enterprise SAML connections. See SSO connections for step-by-step setup and callback URLs.

Domain

Attach a custom domain to serve hosted pages and OAuth2/OIDC endpoints from your own domain. See Custom domains.

Email

Send sign-in emails (codes and magic links) from your own domain. Setup typically involves verifying the sender address (OTP) and then adding DNS records for the domain.

Theme

Upload your logo and set the brand color, backgrounds and corner style for this tenant’s hosted UI. See Branding & theming.

Endpoints

Shows the tenant’s base URL and the key OAuth2/OIDC endpoints (and automatically switches to your custom domain once it’s active).

Apps (redirect URIs)

Apps are created per tenant, but they live under Apps in the Admin UI (not inside the tenant tabs).

  • Redirect URIs are configured on the app and must match exactly what your app sends in the authorize request.
  • Allowed origins (in the tenant General tab) are separate: they control CORS for browser-based calls to the Application API.

For an end-to-end integration walkthrough, see Installation or OAuth2 & OIDC.

SCIM

SCIM provisioning is set up per organization, not on the tenant: each organization's identity provider calls the tenant's /scim/v2 with its own SCIM token. See SCIM provisioning.

Hooks

A hook calls your own HTTP endpoint at a fixed moment in a flow, and its answer can change the outcome. The Hooks tab lists the hooks a tenant can have, with when each runs, whether it's on, and how many of its calls failed in the last 24 hours. Open a hook to reach its Settings and Calls tabs.

Today there is one hook, the Sign-in hook (sign_in in the API). Authalla calls your endpoint after the user signs in and before the app receives tokens. It POSTs a JSON body like this (values are placeholders):

{
  "version": 1,
  "hook_type": "sign_in",
  "tenant_id": 42,
  "tenant_public_id": "{tenant-id}",
  "client_id": "{the app's client_id}",
  "scopes": ["openid", "email"],
  "auth_time": "2026-09-27T10:15:00Z",
  "user": {
    "id": 1234,
    "public_id": "{user-id}",
    "email": "jane@example.com",
    "external_id": "{only when the user has one}"
  }
}

Your endpoint must answer HTTP 200 with a JSON object, and what it returns is added to the access and ID tokens under:

  • https://authalla.com/claims/sign_in

This is useful for enriching tokens with application-specific attributes (organization IDs, roles, entitlements, etc.). See claim references in Sessions & tokens.

On the Settings tab:

  • Call the hook turns it on or off for the tenant.
  • Endpoint URL is where Authalla POSTs. It must use HTTPS and be reachable on the public internet: Authalla doesn't call private, local or link-local addresses, and treats a redirect as a failed call rather than following it.
  • Secret (optional) is sent as Authorization: Bearer <secret>, so your endpoint can check the call comes from Authalla.
  • If the call fails decides what happens when your endpoint times out, can't be reached or doesn't answer a 2xx status with a JSON object: continue the sign-in without the claims, or refuse it.
  • Claims to copy lists the top-level fields of the answer to add as claims. Leave it empty to add the whole answer.
  • Test the hook calls your saved endpoint once as if a user signed in, and shows what would be added. No tokens are issued.

The Calls tab lists every call from the last 90 days, newest first: whether it succeeded, the user, the app, how long it took, the HTTP status and when. Open a call to see the error and where it failed, the fields your endpoint returned, and the claims it added. Filter by outcome to see only failures. A sign-in on the Activity page links each of its hook calls to this tab.

Allowed origins from a deployment pipeline

A browser-based app deployed to a new address, such as a preview deployment for each pull request, needs that address as an allowed origin before it can sign in. The pipeline that deploys it can add the origin with the Management API, and remove it when the deployment is torn down. It needs an account API key with tenants:write; restrict the key to the tenant the previews sign in to.

# On deploy: allow the preview's origin
curl -X POST "https://api.authalla.com/management/v1/tenants/{tenant-id}/allowed-origins" \
  -H "Authorization: Bearer $AUTHALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin":"https://pr-42.preview.example.com"}'

# On teardown: remove it
curl -X DELETE "https://api.authalla.com/management/v1/tenants/{tenant-id}/allowed-origins?origin=https://pr-42.preview.example.com" \
  -H "Authorization: Bearer $AUTHALLA_API_KEY"
  • Adding is safe to repeat. Adding an origin the tenant already allows changes nothing and returns 200; a new origin returns 201. Both return the tenant's whole list, so the pipeline can run the same step on every deploy.
  • Origins are stored as scheme, host and port. A path is dropped and a default port (:443, :80) left out, so https://pr-42.preview.example.com/ and https://pr-42.preview.example.com:443 are the same origin. The first change through the API stores the tenant's existing origins this way too.
  • Removing an origin the tenant doesn't allow returns 404. Removing the last one through the API returns the tenant to allowing the origins of its apps' redirect URIs, as before it had any.
  • GET on the same path lists the origins with tenants:read.

The preview's redirect URI goes on the app, with apps:write (see Apps (redirect URIs)). AI agents connected to the MCP server have the same operations as the list_allowed_origins, add_allowed_origin and remove_allowed_origin tools.

Limits and constraints

  • Tenant count: Authalla does not enforce a hard limit on the number of tenants per account today. In practice, tenants are intended for a small number of coarse boundaries (environments/brands/regions). If you need a very high tenant count, reach out so we can help you avoid operational pitfalls.
  • Allowed origins: up to 50 origins per tenant. Adding a 51st through the Management API returns 409; remove origins of finished deployments to make room.
  • Token lifetime overrides: each token TTL must be between 60 and 31,536,000 seconds (1 minute to 365 days).
  • Custom domains: only one custom domain per tenant is currently supported, and domains must be globally unique across Authalla tenants.

Production checklist

Before you ship a tenant to production:

  1. Create a dedicated prod tenant (and separate dev/staging tenants). See Environments.
  2. In General:
    • Set Allow user registration to the right value for your product.
    • Leave Allow AI agents and MCP clients off unless you want agents to sign your users in.
    • Enable the auth methods you want users to see.
    • Set token lifetimes if you need non-default TTLs (see Sessions & tokens).
    • Add Allowed origins for any browser-based app.
    • Attach production's custom domain now if you want one. Passkeys and sessions belong to the sign-in address, so moving it after launch makes users sign in again and create new passkeys.
  3. In Connections: add social or enterprise connections as needed (see SSO connections).
  4. In Theme and Email: configure branding and your sender domain (see Branding & theming).
  5. In Domain (optional): attach and verify a custom domain (see Custom domains).
  6. Create or verify your app configuration (redirect URIs, secrets, etc.). Start with Installation or OAuth2 & OIDC.
Previous
User API
Next
Environments