Tenant lifecycle

The admin endpoints manage a tenant’s lifecycle. They are identical between the Auth Relay and the Chat Relay, save for a few differences noted below. All are protected by the X-Admin-Key header (an operator key, distinct from tenant secrets).

Admin key

X-Admin-Key is a high-privilege operations key. Never expose it client-side, and use it only from a trusted server context (ops scripts, an admin backend).

Parameter convention

One simple rule, everywhere:

• provision takes a JSON body. It is the only creation call; it receives the tenant’s full configuration in the body.
• Everything else takes ?tenant_id= as a query parameter (update, rotate/*, suspend, reactivate, fetch). update additionally takes a partial body.

Note

update/tenant applies a partial update: only the fields you supply change. It never rotates secrets — use the dedicated rotate/* endpoints.

Endpoints (common shape)

Method	Path	Params	Effect
POST	/provision/tenant	JSON body	Creates the tenant; returns tenant_id + tenant_secret once.
POST	/update/tenant	?tenant_id= + body	Partial config update.
POST	/rotate/tenant-secret	?tenant_id=	New tenant_secret; the old one is invalidated immediately.
POST	/suspend/tenant	?tenant_id=	Blocks signed calls (403) until reactivated.
POST	/reactivate/tenant	?tenant_id=	Lifts the suspension.
GET	/fetch/tenant	?tenant_id=	Returns the config (never the secret).
GET	/fetch/tenants	?limit=&offset=	Paginated list.

Per-relay differences:

• Chat Relay adds POST /rotate/widget-key?tenant_id= and returns a widget_public_key at provisioning. See Tenant management — Chat Relay.
• The exact body shape (branding fields, quotas, options) is specific to each relay: see Tenant management — Auth Relay and Tenant management — Chat Relay.

Rotating a compromised secret

1. Call POST /rotate/tenant-secret?tenant_id=... with X-Admin-Key.
2. Read the new tenant_secret from the response (shown once).
3. Deploy it to your backend’s secrets vault.
4. The old secret stops signing validly immediately: plan for a brief cutover.

Suspend vs delete

Suspension is reversible and immediately blocks all of the tenant’s signed calls (a 403 response). It is the lever to pull during an incident: suspend now, investigate, then reactivate.

Next steps

• Authentication (HMAC) — use the secrets obtained here.
• Tenancy & relay_user_id — the tenancy model.