Tenant Management and SSO

A tenant is your organization's isolated space on Ema — its own users, AI Employees, knowledge bases, and configuration, fully separated from every other tenant. Tenant management is where you configure how the tenant looks, how people sign in, which model providers it uses, and which API keys can call it.

Everything here lives at /admin/tenant-management, a single page with five tabs: Tenant, SSO, Email domains, Providers, and API keys. Each tab maps to a path so you can link directly to it.

Tenant settings and branding

The Tenant tab (/admin/tenant-management/tenant) shows your tenant's identity and lets you configure security and branding.

Overview displays read-only facts: tenant name, tenant ID, slug, and the created and last-updated dates.

Tenant hierarchy lets a system_admin create and manage child tenants. Child tenants are isolated like any tenant but can inherit shared resources and roll metrics up to the parent. Creating a child requires tenant.create_child; viewing children requires tenant.view_children.

Security has one setting: Require TOTP. Turning it on requires every user in the tenant to set up time-based one-time-password (TOTP) two-factor authentication. Enabling it shows a confirmation prompt because it affects all users at next sign-in.

Branding customizes the sign-in experience and notification emails:

• Company URL and Logo URL — both must be https://. The logo URL is verified to load as an image before it's saved.
• TOTP issuer label — the label shown in authenticator apps (up to 64 characters).
• Company name, brand color, support email, and footer text — used in emails.

Templates customizes the one-time-passcode (OTP) sign-in email: subject, greeting, custom message, and sign-off. A live preview is available, and you can reset to the platform default at any time. When SSO is enabled, the OTP email template is not used (users authenticate through your identity provider), and the tab tells you so.

SSO

The SSO tab (/admin/tenant-management/sso) configures single sign-on so users authenticate through your identity provider (IdP) instead of an Ema password or OTP email. Ema supports two protocols:

• OIDC (OpenID Connect)
• SAML 2.0

Configuring SSO

Select Edit, then:

1. Toggle SSO enabled on.
2. Choose the provider type — SAML or OIDC.
3. Enter a provider name (a display label for the sign-in screen).
4. Fill in the protocol-specific fields:
   • OIDC — client ID, client secret, and issuer URL (for example https://auth.example.com).
   • SAML — IdP metadata URL (for example https://idp.example.com/metadata) and entity ID (for example urn:example:sp).
5. Set a default role — the role assigned to a user on their first SSO sign-in if they don't already have a membership. Options are User, Builder, User Admin, Builder Admin, and No Access. Defaulting to No Access is the safe choice when you want to approve each user explicitly.
6. Save.

When SSO is enabled but no email domains are claimed yet, the tab nudges you to claim at least one — domains are how Ema routes a user's email to your IdP. See Email domains.

To stop using SSO, Edit and then Delete the configuration.

Redirect URIs

Register these callback URLs with your identity provider; they must match exactly:

• OIDC — /auth/oidc/callback
• SAML — /auth/saml/acs (the SAML assertion consumer service)

For SAML, Ema also publishes service-provider metadata at GET /auth/saml/metadata?tenant=<slug> that you can import into your IdP.

How SSO sign-in routes

When a user enters their email on the sign-in screen, Ema discovers the right method from the email's domain (GET /auth/sso/discovery). If the domain is claimed by an SSO-enabled tenant, the user is redirected to that IdP; otherwise they fall back to password or OTP sign-in.

Endpoints

Email domains

The Email domains tab (/admin/tenant-management/email-domains) is where you claim and verify the email domains your tenant owns. Domains serve two purposes: they gate who you can invite (an invitee's domain must be claimed by your tenant or an ancestor), and they route SSO sign-in to your IdP.

Claiming and verifying a domain

1. Select Claim domain and enter the domain (for example example.com). The claim is created in pending status.
2. Ema returns a verification token and DNS instructions. Add the provided TXT record to your domain's DNS.
3. Select Verify. Ema checks for the DNS TXT record and, on success, moves the claim to verified. If the record isn't found yet, verification returns an error — DNS can take time to propagate, so retry after a few minutes.

A claimed domain looks like this:

{
  "id": "d1c2...",
  "tenant_id": "a07d...",
  "domain": "example.com",
  "status": "pending",
  "verification_token": "ema-verify-7f3a9c...",
  "dns_instruction": "Add a TXT record to example.com with value ema-verify-7f3a9c...",
  "verified_at": null,
  "created_at": "2026-05-30T14:22:10Z"
}

Endpoints

Model providers

The Providers tab (/admin/tenant-management/providers) configures bring-your-own-model (BYOM) providers — your own API credentials for an LLM vendor — so EmaFusion™ can route to models on your account. Supported provider types are Azure OpenAI, OpenAI, Anthropic, Google AI Studio, Groq, Fireworks, DeepSeek, Perplexity, Mistral, and Custom (OpenAI-compatible). Azure OpenAI and Custom require a base URL; Azure OpenAI also requires a deployment name.

For each configured provider, a table lists its models with per-model toggles to enable or disable them for the tenant. Disabling a model removes it from the pool EmaFusion™ can select. Managing providers requires builder_admin or system_admin.

API keys

The API keys tab (/admin/tenant-management/api-keys) issues and revokes keys for programmatic access to your tenant. A key authenticates API calls on behalf of the tenant; it can be exchanged for a short-lived access token. Managing keys requires the auth.manage_api_keys capability (builder_admin or system_admin).

Creating a key

1. Select New key and give it a descriptive name.
2. Create the key. The full secret is shown once, at creation time — copy it immediately and store it securely. After you close the dialog it cannot be retrieved again; only the key prefix is shown thereafter.

Listing and revoking

The table shows each key's name, its non-secret prefix, and its creation date. To revoke a key, open its actions menu and select Revoke — revocation is immediate and cannot be undone. An activity feed on the tab records key creation and revocation events.

Endpoints

What's next

• User management — invite users once domains are claimed.
• PII and data governance — control how sensitive data is shown and shared.
• Audit log — every SSO, domain, provider, and key change is recorded.