Skip to content

Tenants

Koldan Cloud only

A tenant is an isolated workspace within a Koldan Cloud deployment. Each tenant has its own users, roles, quotas, rate limits, retention policies, and subscription plans - completely separated from other tenants on the same platform.

On-premise deployments operate with a single default tenant that is created automatically on first startup. Multi-tenancy is a cloud-only capability.

How Tenants Work

Every tenant is a self-contained environment. When a user authenticates and hits an API endpoint, Koldan resolves which tenant they belong to and enforces that tenant's configuration:

Aspect Per-Tenant Isolation
Users Each tenant has its own user directory - a user in one tenant does not exist in another
Roles The tenant defines which role is assigned to the first user (tenant owner) and which role new users receive by default
Quotas & Rate Limits Default quotas and rate limits are configured at the tenant level and serve as the baseline for all users
Retention Policies Data retention durations are set per tenant
Subscription Plans Plans are scoped to the tenant that created them
Identity Provider Each tenant can connect its own OIDC identity provider (see BYOIdP below)

Tenant Resolution

When an API request arrives, Koldan determines which tenant context to use. The resolution follows this order:

Priority Source Description
X-Tenant-Id header Explicitly specifies the target tenant (UUID)
Default tenant If no header is provided, the default tenant is used 
GET /api/v1/transcriptions HTTP/1.1
Host: koldan.dixilang.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
X-Tenant-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890

When do you need X-Tenant-Id?

Most customers have a dedicated URL for their tenant (e.g., acme-koldan.dixilang.com) and never need to send this header - the platform resolves the tenant from the hostname. The X-Tenant-Id header is only necessary when a single API gateway serves multiple tenants at the same URL, which is typically limited to platform administrators.

The Default Tenant

Every Koldan deployment - including on-premise - has a default tenant that is bootstrapped automatically on first startup. It:

  • Uses the well-known ID 00000000-0000-0000-0000-000000000001
  • Can be configured with an OIDC provider via environment variables or later through the API

On-premise deployments use only this default tenant and do not need to think about multi-tenancy at all.

Bring Your Own Identity Provider

Each tenant can connect its own OpenID Connect (OIDC) identity provider - Keycloak, Azure AD, Okta, Auth0, Google Workspace, or any OIDC-compliant IdP. This is what we call BYOIdP (Bring Your Own Identity Provider).

Why BYOIdP?

  • Single Sign-On (SSO) - users sign in with their existing corporate credentials, no separate Koldan password needed.
  • Centralized user management - onboarding and offboarding is handled in your IdP; Koldan automatically creates accounts on first login and respects token revocation.
  • Security policies - MFA, password complexity, session duration, and conditional access are all managed by your IdP.
  • Compliance - credentials never touch Koldan's servers; authentication is fully delegated to your IdP.

How It Works

sequenceDiagram
    participant User
    participant Client as Client App
    participant Koldan as Koldan API
    participant IdP as Your Identity Provider

    User->>Client: Sign in
    Client->>IdP: Redirect to authorization endpoint
    IdP->>User: Prompt for credentials + MFA
    User->>IdP: Authenticate
    IdP->>Client: Authorization code
    Client->>Koldan: Exchange code for token
    Koldan->>IdP: Validate code at token endpoint
    IdP->>Koldan: Access token + refresh token
    Koldan->>Client: Session established
    Note over Client,Koldan: Subsequent API calls use<br/>the Bearer token
  1. The client application redirects the user to the tenant's configured authorization endpoint.
  2. The user authenticates with their IdP (password, MFA, SSO, etc.).
  3. The IdP returns an authorization code to the client.
  4. The client sends the code to Koldan, which exchanges it at the IdP's token endpoint for an access token.
  5. Koldan validates the token using the IdP's JWK Set (public keys) - it never sees or stores user passwords.
  6. On first login, Koldan auto-creates the user account and assigns the tenant's configured default role.

OIDC Provider Configuration

Each tenant's OIDC provider requires the following endpoints:

Endpoint Required Description
Issuer URI The OIDC issuer URL (e.g., https://idp.example.com/realms/acme)
Token URI Where authorization codes are exchanged for tokens
JWK Set URI Public keys for validating JWT signatures
Client ID The OAuth2 client ID registered in your IdP
Client Secret Required for confidential clients; encrypted before storage and never returned by the API
Authorization URI Login page endpoint - required for interactive sign-in flows
UserInfo URI Optional endpoint for fetching additional user claims
End Session URI Logout endpoint - enables remote session invalidation
Introspection URI Token introspection for real-time revocation checks
Public Issuer URI Alternative issuer URL advertised to clients (e.g., an external-facing URL that differs from the internal issuer)

Defaults

  • User name attribute defaults to sub - the standard OIDC subject claim.
  • Scopes default to openid profile email.

Setting Up Your IdP

To connect your identity provider to a Koldan tenant:

  1. Register a client in your IdP (e.g., create an "Application" in Azure AD or a "Client" in Keycloak).
    • Set the redirect URI to your Koldan instance URL (provided by your administrator).
    • Enable the Authorization Code grant type.
    • Note the Client ID and Client Secret.
  2. Collect the OIDC endpoints - most IdPs publish a discovery document at /.well-known/openid-configuration under the issuer URL. From there you can find the token, JWK set, authorization, and other endpoints.
  3. Provide the configuration to your Koldan platform administrator, who will configure it via the Admin Tenants API.

Testing the connection

After configuration, the administrator can use the OIDC provider test endpoint to verify connectivity. This performs a client_credentials grant against your IdP and confirms that Koldan can reach the token endpoint and validate the response.