Skip to main content

Auth API

The Auth service wraps Clerk for identity management and handles user synchronization with GospeLib's internal database.

OpenAPI Spec Not Yet Created

This API reference will be auto-generated from services/auth/api/openapi.yaml using docusaurus-plugin-openapi-docs once the OpenAPI spec is created. The content below is a high-level summary.

What This API Covers​

User Management​

  • GET /api/v1/users/me — Retrieve the current authenticated user's profile
  • PUT /api/v1/users/me — Update profile information

Authentication Flow​

The Auth service does not expose login/signup endpoints directly. Authentication is handled client-side via Clerk's SDKs. The service:

  1. Validates JWTs issued by Clerk at the gateway layer
  2. Syncs user records from Clerk to PostgreSQL via webhooks
  3. Injects X-User-Id into downstream requests

Clerk Webhooks​

The Auth service receives Clerk webhook events for user lifecycle management:

  • user.created — Create internal user record
  • user.updated — Sync profile changes
  • user.deleted — Soft-delete internal record

Webhook payloads are verified using Clerk's signing secret. Idempotency keys are stored in PostgreSQL to prevent duplicate processing.

Authentication​

All /api/v1/users/* endpoints require a valid Bearer token. See the API Overview for details.