Authentication

Overview

Intry uses different auth mechanisms depending on which surface you call. See Architecture — Auth for the full picture.

Operators sign in through the admin dashboard. The SPA obtains a session from WorkOS; subsequent API calls include the session cookie. Implementation: src/routes/admin/auth.ts, src/middleware/workosAuth.ts.

Clerk (migration)

Modern admin gateway uses Clerk Organizations. Staff routes may accept Clerk bearer tokens via src/lib/clerkBearerAuth.ts.

Unkey (machine clients)

Automations, MCP servers, and CI jobs should use Unkey-issued API keys:

Authorization: Bearer <unkey_api_key>

Keys carry scopes and rate limits. Rotate keys from /api/admin/api-keys when staff changes roles.

See docs/AGENT_UNKEY_KEYS.md and docs/UNKEY_AND_API_AUTHENTICATION.md.

Resident API (`/api/v1/*`)

Clerk session exchange (portal)

POST /api/v1/auth/clerk-session
Authorization: Bearer <clerk_session_token>

Returns a Core JWT for subsequent /api/v1/* calls (match resident by email).

/registration/* handles resident signup and login (bcrypt passwords, JWTs). Prefer /api/v1/auth/* for new integrations.

JWT on protected routes

Authorization: Bearer <core_jwt>

Middleware: requireAuth() in src/middleware/jwtAuth.ts.

Device registration

/devices/* associates FCM/APNs tokens with a Device row. Requires authenticated user context.

Webhook signature verification

Provider	Path prefix	Header
Twilio	`/twilio/*`	`X-Twilio-Signature`
Telnyx	`/telnyx/*`	Telnyx Ed25519 signature
Stripe	`/stripe`	`Stripe-Signature`
Clerk	`/webhooks/clerk`	Clerk webhook secret

Never expose webhook URLs without signature verification enabled.

Practical checklist

TLS enabled end-to-end in production
X-Admin-Env set correctly when using the admin proxy
Unkey keys scoped to least privilege
Secrets stored in Railway/Fly dashboards, not committed to git

Last verified: 2026-06-21 (commit 293c4a7)