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: clients 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).

Most teams should start with one tenant per environment:

  • Development
  • Staging
  • Production

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.

Overview

  • Allow user registration (allow_registration): If enabled, new users can sign up in this tenant. If disabled, users must already exist (or be provisioned via SSO/SCIM) to sign in.

  • Authentication methods (auth_methods): Controls what end users see on the login page:

    • magic_link: Magic link / PIN code (email)
    • passkeys: Passkeys (WebAuthn)
    • social_logins: Social login buttons
    • enterprise_sso: Enterprise SSO routing (OIDC/SAML)

    Forced SSO mode: if only enterprise_sso is enabled, users must authenticate via their corporate IdP.

  • 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.

SSO Providers

Configure social login, enterprise OIDC, and SAML SSO 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 authentication emails (login codes, magic links, password resets) 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 customize light/dark colors 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).

OAuth Clients (redirect URIs)

OAuth2 clients are created per tenant, but they live under OAuth Clients in the Admin UI (not inside the tenant tabs).

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

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

SCIM

Shows the tenant SCIM base URL (/scim/v2) and the OAuth2 token endpoint to use for provisioning. SCIM requires a client credentials token with SCIM scopes enabled.

API

Configure Allowed origins (CORS) for browser-based apps calling the Authalla Public API from a web origin.

This is required for SPAs that call the Public API directly from the browser. Include the full origin, including protocol, for example:

  • https://app.example.com
  • http://localhost:3000

Backend-to-backend calls do not use CORS.

Hooks

The most commonly used tenant hook is the post-login hook: Authalla calls your HTTP endpoint after the user is authorized but before tokens are minted. The response can be embedded into issued tokens under:

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

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

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.
  • 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).
  2. In Overview:
    • Set Allow user registration to the right value for your product.
    • Enable the auth methods you want users to see.
    • Set token lifetimes if you need non-default TTLs (see Sessions & tokens).
  3. In SSO Providers: configure social login / enterprise SSO as needed (see SSO connections).
  4. In API: add Allowed origins for any browser-based Public API usage.
  5. In Theme and Email: configure branding and your sender domain (see Branding & theming).
  6. In Domain (optional): attach and verify a custom domain (see Custom domains).
  7. Create or verify your OAuth2 client configuration (redirect URIs, secrets, etc.). Start with Installation or OAuth2 & OIDC.
Previous
Sessions & tokens
Next
Custom domains