Authentication
WorkOS, Clerk, JWT, and Unkey across Intry surfaces.
Intry uses different auth mechanisms per surface. ADR-004 target: Clerk everywhere; WorkOS is being retired but still active for some admin flows.
Deep runbook: docs/AUTH_ARCHITECTURE.md in the monorepo.
| Aspect | Detail |
|---|
| Who | Platform admins, property managers, staff |
| Login | WorkOS SSO (legacy cookie wos-session) or Clerk Organizations via intry-admin gateway |
| Routes | /api/admin/* |
| Middleware | requireAdmin() in src/middleware/workosAuth.ts; Clerk bearer for comms routes |
| Aspect | Detail |
|---|
| Login | Clerk or legacy email + password (POST /registration/login) |
| Auth | JWT Bearer on subsequent requests |
| Routes | /api/v1/*, /access/*, /devices/* |
| Aspect | Detail |
|---|
| Login | Clerk only (sign-in / sign-up) |
| Backend exchange | POST /api/v1/auth/clerk-session — Clerk session token → Core JWT (match by email) |
| Routes | Same JWT-protected /api/v1/* as mobile |
| Client | Method |
|---|
| MCP, CI, scripts | Unkey API key: Authorization: Bearer <key> |
| Scopes | Least-privilege scopes on /api/admin/api-keys |
See docs/AGENT_UNKEY_KEYS.md and docs/UNKEY_AND_API_AUTHENTICATION.md.
| Provider | Verification |
|---|
| Twilio | X-Twilio-Signature HMAC |
| Telnyx | Ed25519 {timestamp}|{body} |
| Stripe | Stripe-Signature header |
| Clerk | verifyWebhook() from @clerk/backend/webhooks |
| Surface | Clerk primitive | Role source |
|---|
| intry-admin | Clerk Organization | org:role session claim |
| intry-portal | Clerk User | User metadata |
| intry-app | Clerk User | User metadata |
| intry-core API | Clerk session token | @clerk/backend verify |
Middleware target names: requirePlatformAdmin, requireOwner, requireResident — not yet fully implemented; use current middleware until migration completes.
| File | Purpose |
|---|
src/middleware/workosAuth.ts | Admin WorkOS session |
src/middleware/jwtAuth.ts | Resident JWT (requireAuth) |
src/lib/clerkBearerAuth.ts | Clerk token verification |
src/routes/clerk-webhook.ts | User/org sync webhooks |
Last verified: 2026-06-21 (commit 293c4a7)