Tenancy & Onboarding

Everything on APEX is tenant-scoped: credentials, configuration, corpora, message history, usage records. Your platform is (at least) one tenant. This page covers how a tenant comes to exist, what you receive, and the tenancy rules every integration must respect.

What a tenant is

A tenant is the unit of isolation and entitlement:

• Identity — a slug (e.g. your-tenant, pattern ^[a-z0-9-]+$) used in URLs, scopes, and configuration.
• Entitlements — which products are enabled, at which tier, with which limits.
• Configuration — per-product settings (models, channels, templates, verification behaviour) held centrally by Forge, the platform's configuration authority.
• Credentials — API keys and machine-to-machine clients bound to the tenant.

Onboarding — what you request, what you receive

Onboarding is operator-led. Provide:

1. Desired tenant slug and display/organisation name.
2. Products you need enabled, and expected volumes.
3. An administrator email (seeds the first portal membership — without it nobody can sign in to manage the tenant).
4. For messaging: channels required and sender identities (e.g. email domain to verify, WhatsApp business number).
5. For knowledge: where your corpus lives and how it should be ingested.

You receive:

1. Tenant slug — confirmed.
2. Tenant API key (test-class for development) — the runtime credential.
3. Machine-to-machine credential bundle — client id, secret, token URL, and your scope list.
4. Base URLs for your environment.
5. Portal access for your administrators (tenant detail, API keys, billing, audit).

Programmatic provisioning (for factories)

If your organisation creates tenants repeatedly (a venture factory, a reseller), tenant creation is itself an API: POST /api/tenants on the Forge portal, authenticated with a machine-to-machine token carrying the forge/tenant.write scope, with an Idempotency-Key: provision:<uuid> header making retries replay-safe. Creation returns 201 when complete, or 202 with a status URL to poll while runtime resources finish provisioning. See openapi/forge-portal.yaml. Provisioner credentials are granted explicitly by the platform operator.

Tenancy rules your integration must respect

1. Explicit tenant on every call

Every request names its tenant. The carriage differs per product — this table is normative:

The named tenant must match your credential's tenant. A mismatch is rejected with 403 — never retry a mismatch unchanged; it means a wiring bug.

2. Fail-closed configuration is a feature

Forge is the configuration authority. A product that has no configuration for your tenant refuses to serve it — typically 404 (tenant unknown) or 403 (not entitled). Design for it:

• Treat "tenant not configured for product X" as a first-class application state with a clear operator-facing message.
• Do not mask it as a generic error or retry it; it resolves through configuration, not code.

3. Configuration changes propagate without redeploys

Operators change tenant configuration centrally; products pick it up automatically (push, with a polling backstop — allow up to ~60 seconds). Your application should tolerate entitlements appearing or changing between calls without restart.

4. Tenant lifecycle

Tenants move through a managed lifecycle — created, product enabled, configured, product disabled, archived. Disablement is effective at the product surface (calls fail closed) even while your credentials remain technically valid. Handle it as in rule 2.

Multi-tenant client platforms

If your platform serves your own customers, you have two models:

1. One APEX tenant per end-customer — strongest isolation; use programmatic provisioning; your backend selects the tenant credential per request.
2. One APEX tenant for your platform — your application enforces customer separation internally; APEX sees one tenant.

Which applies is a commercial/architectural decision made with your platform contact during onboarding — data-isolation obligations (e.g. per-client corpus ownership) usually decide it.