External Integrations
Authentication and Tenant Context
Authentication modes currently implemented by the API and how tenant scoping is enforced.
Auth Modes
| Mode | Header | Used For | Notes |
|---|---|---|---|
| Clerk JWT | Authorization: Bearer <clerk_jwt> | All /v1/* and /admin/* endpoints | Tenant context is resolved from org_id claim (or X-Tenant-ID fallback where applicable). |
| Device API key (dak_) | Authorization: Bearer <device_api_key> | Authenticated /devices/:id/* runtime endpoints | Issued once by POST /devices/register and stored only as hash server-side (device_api_keys table). |
| Tenant machine key (ak_) | Authorization: Bearer <tenant_api_key> | Tenant-managed machine integrations (key material from /v1/api-keys) | Managed in api_keys table; create/rotate/revoke endpoints require tenant_admin or super_admin role. |
Tenant Scoping Rules
- All /v1/* and /admin/* endpoints require Authorization: Bearer <clerk_jwt>.
- Tenant is primarily derived from Clerk org_id claim.
- When org_id is unavailable, some flows can use X-Tenant-ID fallback.
- Requests missing tenant context fail with AUTH_NO_ORGANIZATION or AUTH_TENANT_CONTEXT_REQUIRED depending on route.
- Device runtime endpoints authenticate through device_api_keys hashes, not Clerk sessions.
Header Examples
Clerk JWT
Authorization: Bearer <clerk_jwt> X-Tenant-ID: <tenant_id_optional_fallback>
Device API Key
Authorization: Bearer <dak_device_api_key>