Authentication

API keys

The primary auth method is an API key issued from the portal.

• Format: ck_live_<base32> — 256 bits of entropy.
• Header: Authorization: Bearer ck_live_…
• Scope: per-organisation. Sub-organisations (partner mode) get distinct keys with their own quotas, rate limits, and balances.
• Rotation: rotate at any time from API keys → Rotate. The previous key keeps working for 24 hours.
• Revocation: instant. Revoked keys return 401 with a structured error.code: "key_revoked" payload.

OIDC SSO

For human (portal) login, the gateway exposes a standard OIDC discovery surface:

Endpoint	Path
Discovery	/.well-known/openid-configuration
JWKS	/oauth/jwks
Userinfo	/oauth/userinfo
Token	/oauth/token (standard OAuth2)
Authorize	/oauth/authorize

Today this is backed by Laravel Passport. Authentik is being rolled in to take over the user-facing flows on auth.cloakapi.io — see the operations section once that ships.

Per-request scoping

Inside the gateway, requests are scoped by:

• Tenant — derived from the API key.
• Sub-organisation — for partner / white-label flows.
• Capability — fine-grained allowlist (gpt-4o, bedrock:claude, …) enforced before provider routing.
• Quota — monthly token budget per (tenant, capability).
• Rate limit — sliding-window per (tenant, capability) at 60s and 3600s scales.