Authentication & Authorization

Wordloop delegates absolute identity management to Clerk while retaining local user schemas strictly to anchor database relations.

[!IMPORTANT] Internal services rely on symmetric tokens for system-level trust. Zero-trust principles apply at external boundaries; inherited trust applies internally.

User Authentication Flow (Clerk)

Clerk acts as our authoritative identity provider (IdP).

Frontend Implementation

• Identity Context: wordloop-app uses @clerk/nextjs for all auth flows.
• Header Injection: JWT tokens are automatically injected into wordloop-core requests as Authorization: Bearer <token> by the Orval API clients via a custom fetch interceptor.

Backend Validation

• Middleware: wordloop-core uses robust Clerk middleware within the Huma framework.
• Verification: The middleware validates the JWT symmetrically against Clerk's JWKS endpoint, extracting the clerk_user_id directly into the Request context.Context.

Data Synchronization

To link auth identities with core business entities (like Meetings or Transcripts), users are synchronized into the local Postgres database.

[!NOTE] Database synchronization occurs asynchronously via Clerk Webhooks.

1. User Creation: When a user registers, Clerk fires a user.created webhook to wordloop-core.
2. Database Sink: Core validates the Svix headers, parses the webhook payload, and idempotently upserts the record into the users table.

Service-to-Service Authentication

When internal services communicate outside of standard user contexts (e.g., the ML engine pulling an audio binary from Core API endpoints), they use a static symmetric token.

• Header Specification: Authorization: Bearer <SERVICE_AUTH_TOKEN>
• Assumed Scope: Full administrative access.

[!WARNING] Never expose the SERVICE_AUTH_TOKEN to the frontend or public-facing API routes. This token bypasses user validation logic.