Auth flow
Clerk sessions and how the portal talks to Intry Core.
Overview
The portal delegates identity to Clerk. After sign-in, the portal exchanges the Clerk session for a Core JWT via POST /api/v1/auth/clerk-session (match resident by email).
Deep runbook: docs/AUTH_ARCHITECTURE.md.
Flow
- Resident signs in with Clerk (sign-in / sign-up).
- Portal server calls Core with Clerk session token.
- Core returns JWT if matching
Userrow exists. - Portal uses JWT for all subsequent
/api/v1/*calls.
Components
| Piece | Responsibility |
|---|---|
| Clerk middleware | Protects routes, refreshes sessions |
| Next.js Route Handlers | Exchange Clerk → JWT; proxy Core calls server-side |
Core User | Must contain matching email (and optionally clerkUserId) |
Environment variables
| Variable | Purpose |
|---|---|
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY | Client-side Clerk |
CLERK_SECRET_KEY | Server-side Clerk + Core webhook |
| Core base URL | API host for BFF routes |
Never expose Core Unkey keys to the browser.
Testing
Use Clerk test users and separate Clerk instances per environment. Rotate webhook signing secrets when enabling Clerk webhooks for user sync.
Last verified: 2026-06-21 (commit 293c4a7)