Tenants

A tenant is one customer organisation. It belongs to the workspace, not to a project or an environment: a customer who uses two of your APIs in both test and live is still one tenant, so they are counted once.

Tenants → New tenant takes an external id and a name. The external id is unique per workspace and is meant to be your identifier for that customer, so a tenant lookup from your side never needs a mapping table.

curl -X POST https://keyring-api.belghalem.fr/v1/tenants \
  -H "Authorization: Bearer $KEYRING_SECRET_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"external_id":"acme-corp","name":"Acme Corp"}'

{
  "object": "tenant",
  "id": "01a0...",
  "external_id": "acme-corp",
  "name": "Acme Corp"
}

What the tenant page shows

The tenant's page in the dashboard has its usage per project and environment, its keys, its settings (name and a free-form meta object), its embed sessions, and a delete control.

What a tenant is for

• Verification. req.keyring.tenantId is the tenant the calling key belongs to. Your handler scopes its query on it.
• Rate limits with scope: 'tenant' share one counter across every key the tenant holds, which is what "this organisation gets 10,000 a day" means and what survives a rotation.
• Idempotency is scoped per (project, env, tenant), so a retry that arrives on a freshly rotated key still finds the record the old key wrote.
• Billing. The billable unit is an active tenant per month, counted from live traffic only. Test-mode traffic never enters that count.

Deleting a tenant

Deleting a tenant revokes its keys in the same transaction, the same way deleting a project does.