convex-auth

name

convex-auth

description

Implement Convex authentication and authorization patterns with OIDC providers or Convex Auth. Use for auth provider setup, ctx.auth usage, user identity handling, and auth-aware schema patterns. Use proactively when users mention auth, JWT, Clerk/Auth0/WorkOS, or Convex Auth. Examples: - user: "Add auth to Convex" → choose provider and outline setup - user: "Get current user" → use ctx.auth.getUserIdentity and checks - user: "Service-to-service access" → use shared secret pattern

Implement Convex authentication and authorization patterns with OIDC providers (Clerk, Auth0, WorkOS) or the built-in Convex Auth library. - **Auth overview**: https://docs.convex.dev/auth - **Convex Auth (beta)**: https://docs.convex.dev/auth/convex-auth - **Auth methods**: https://labs.convex.dev/auth - **Clerk Integration**: https://docs.convex.dev/auth/clerk - **WorkOS Integration**: https://docs.convex.dev/auth/authkit/ - Convex uses OpenID Connect JWTs. - Integrations: Clerk, WorkOS AuthKit, Auth0; custom OIDC supported. - Convex Auth (Beta): A built-in library (labs.convex.dev) supporting Magic Links, OTPs, OAuth, and Passwords without external services. - Identity: Accessed via `ctx.auth.getUserIdentity()` in server functions. - Authorization: Enforced per public function; sensitive logic MUST use internal functions.

Auth Operations

• In functions: ctx.auth.getUserIdentity() returns tokenIdentifier, subject, issuer plus provider claims.
• Custom JWT auth MAY expose claims at identity["properties.email"] style paths.
• User storage patterns:
  • Client mutation to store user from JWT, or webhook from provider to upsert users.
  • Index lookups SHOULD use by_token / byExternalId.
• Webhooks: You MUST implement via HTTP actions and verify signatures with provider SDK; signing secrets MUST be stored in env vars.

Convex Auth (Beta) Specifics