Authentication

Hybrid model: JWT (UI / people) + API keys (agents / integrations) + optional SSO/OIDC.

Login (JWT)

bash curl -X POST http://localhost:8000/api/v1/auth/login \ -H "Content-Type: application/json" \ -d '{"email":"admin@example.com","password":"your-password"}'

The response includes access_token and the user profile (tenant_id included).

API keys

User / SDK keys (abi_)

```bash export JWT=""

curl -X POST http://localhost:8000/api/v1/auth/api-keys \ -H "Authorization: Bearer $JWT" \ -H "Content-Type: application/json" \ -d '{"name":"Production","notes":"Agent SDK"}' ```

raw_key (abi_...) is returned once. Header: X-API-Key: abi_...

Tenant keys (bt_)

Created with POST /api/v1/tenants (super_admin JWT or X-Admin-Key). Use for ingest scoped to that business tenant.

SSO / OIDC

Supported providers (env-flagged): Google, Keycloak, Okta, Microsoft Entra ID.

1. Set SSO_PUBLIC_BASE_URL / SSO_FRONTEND_URL to the public HTTPS origin.
2. Enable a provider, e.g. GOOGLE_SSO_ENABLED=true + client id/secret.
3. IdP redirect URI: {SSO_PUBLIC_BASE_URL}/api/v1/auth/sso/callback
4. Map email domains on tenants (allowed_email_domains) before users sign in — via Users → Organizations (super_admin) or PATCH /tenants/{id}. Domains are unique across tenants.

Flow: /auth/sso/login → IdP → /auth/sso/callback (JWKS-verified ID token + nonce) → frontend /login.html?sso_code= → /auth/sso/exchange → JWT.

Unknown email domains are rejected (no silent attach to Default Business).

SSO-assigned roles are capped at admin — IdP claims never grant super_admin (platform role stays local-only).

Roles (RBAC)

Role	Description
super_admin	Platform — all tenants (requires X-Tenant-Id for analytics)
admin	Tenant admin — users, agents, billing
executive	CEO/CFO — dashboards and reports
manager	Operational manage + API keys
viewer	Read-only

Multi-tenant isolation

All agents, events, metrics, ROI, and reports are scoped by tenant_id. JWT/abi_ inherit the user tenant; bt_ keys bind to the tenant that owns the key.

Email domains vs vanity host

Field	Meaning
allowed_email_domains	SSO: which email domains join this tenant (unique globally)
custom_domain	Optional app vanity hostname (Settings → Domain; not auto-routed)

When SSO_SYNC_ROLES=true, SSO may promote roles from IdP claims but will not demote an admin-assigned role, and never assigns super_admin.