Authentication & Authorization

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

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.

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.