# Convex Auth

> Vortex-native, full-stack authentication for Convex.

Convex Auth is a Convex-native authentication library (sessions, OAuth, passkeys, organizations, API keys, webhooks, MCP OAuth) published as @vortex-api/convex-auth. Use these docs when integrating it into a Convex app.

## Docs

- [Introduction](https://labs.vortex.nyc/convex-auth): Convex-native auth for production apps.

## Get started

- [Installation](https://labs.vortex.nyc/convex-auth/installation): Install convex-auth, generate keys, and set your environment variables.
- [Quickstart](https://labs.vortex.nyc/convex-auth/quickstart): Get convex-auth running in a new Convex app in 10 minutes.
- [Concepts](https://labs.vortex.nyc/convex-auth/concepts): The five building blocks of convex-auth for engineers new to Convex.
- [Architecture](https://labs.vortex.nyc/convex-auth/architecture): How convex-auth is designed around Convex's runtime constraints.
- [Configuration](https://labs.vortex.nyc/convex-auth/configuration): Every option on the convexAuth helper and the providers it accepts.
- [Server API](https://labs.vortex.nyc/convex-auth/server-api): Actions, queries, and HTTP routes re-exported by convexAuth.
- [How we got here](https://labs.vortex.nyc/convex-auth/how-we-got-here): Why convex-auth exists and the path that led to the current architecture.

## Framework guides

- [React](https://labs.vortex.nyc/convex-auth/react): React hooks and the client for convex-auth.
- [TanStack Router](https://labs.vortex.nyc/convex-auth/tanstack-router): Client-side route guards with convex-auth in a TanStack Router app.
- [React Native / Expo](https://labs.vortex.nyc/convex-auth/react-native): convex-auth in a React Native or Expo app.
- [Next.js](https://labs.vortex.nyc/convex-auth/nextjs): SSR auth for Next.js with HttpOnly cookie sessions.
- [TanStack Start](https://labs.vortex.nyc/convex-auth/tanstack-start): SSR auth for TanStack Start with HttpOnly cookie sessions.
- [Hono](https://labs.vortex.nyc/convex-auth/hono): SSR auth for Hono with HttpOnly cookie sessions — one middleware is the whole server surface.

## Core auth

- [Email and password](https://labs.vortex.nyc/convex-auth/email-password): Configure email/password sign-up, sign-in, email verification, and password reset.
- [OAuth](https://labs.vortex.nyc/convex-auth/oauth): Google, GitHub, and Discord sign-in with server-side state and PKCE.
- [Generic OAuth](https://labs.vortex.nyc/convex-auth/generic-oauth): Add arbitrary OAuth 2.0 providers to convex-auth.
- [Two-factor authentication](https://labs.vortex.nyc/convex-auth/two-factor): TOTP and backup codes with convex-auth.
- [Magic links](https://labs.vortex.nyc/convex-auth/magic-links): Password-less email sign-in with convex-auth.
- [Email OTP](https://labs.vortex.nyc/convex-auth/email-otp): One-time email passcodes for sign-in and verification with convex-auth.
- [Passkeys](https://labs.vortex.nyc/convex-auth/passkeys): WebAuthn passkey sign-in and registration with convex-auth.
- [Anonymous](https://labs.vortex.nyc/convex-auth/anonymous): Let users try your app without credentials, then link to a real account later.

## Application features

- [Organizations](https://labs.vortex.nyc/convex-auth/organizations): B2B workspaces, members, invitations, and roles with convex-auth.
- [API keys](https://labs.vortex.nyc/convex-auth/api-keys): Create, list, rotate, and revoke machine-scoped API keys with convex-auth.
- [Service principals](https://labs.vortex.nyc/convex-auth/service-principals): Create and manage machine identities and service-owned API keys with convex-auth.
- [OIDC Provider](https://labs.vortex.nyc/convex-auth/oidc-provider): Use convex-auth as an OAuth 2.1 / OpenID Connect provider.
- [Webhooks](https://labs.vortex.nyc/convex-auth/webhooks): Send signed webhook events from convex-auth.
- [Theming](https://labs.vortex.nyc/convex-auth/theming): How to theme and customize the appearance of @vortex-api/convex-auth React components.

## UI components

- [UI components](https://labs.vortex.nyc/convex-auth/components): A complete drop-in UI library for auth — sign-in, organizations, profile, API keys, webhooks — for React and React Native.
- [React Native](https://labs.vortex.nyc/convex-auth/components/react-native): The Expo component set — auth screens, org components, session and profile management.

### React

- [Sign-in & onboarding](https://labs.vortex.nyc/convex-auth/components/react/sign-in): Complete sign-in, sign-up, and post-auth pages plus trigger buttons.
- [Organizations](https://labs.vortex.nyc/convex-auth/components/react/organization): Org switcher, member lists, invites, roles, and profile surfaces.
- [Account & profile](https://labs.vortex.nyc/convex-auth/components/react/account): User profile, sessions, email/password, and 2FA management UI.
- [API keys](https://labs.vortex.nyc/convex-auth/components/react/api-keys): Drop-in forms and lists for issuing and managing API keys.
- [Webhooks](https://labs.vortex.nyc/convex-auth/components/react/webhooks): Endpoint and delivery management UI for signed webhooks.
- [Security audit](https://labs.vortex.nyc/convex-auth/components/react/security): Security audit log list and row components.
- [Providers & primitives](https://labs.vortex.nyc/convex-auth/components/react/providers): Providers, boundary components, shared primitives, and theming.

## Migrations

- [Migrating from Better Auth](https://labs.vortex.nyc/convex-auth/migrating-from-better-auth): One-time cutover from Better Auth to the native convex-auth runtime.
- [Migrating from Clerk](https://labs.vortex.nyc/convex-auth/migrating-from-clerk): Concept mapping and the manual cutover path from Clerk to convex-auth.
- [Migrating from WorkOS](https://labs.vortex.nyc/convex-auth/migrating-from-workos): Concept mapping and the manual cutover path from WorkOS AuthKit to convex-auth.
- [Migrating to per-feature components](https://labs.vortex.nyc/convex-auth/migrating-to-feature-gated-components): Move from the all-in-one component to installing only the auth features you use.
- [Migrating to v3](https://labs.vortex.nyc/convex-auth/v3-migration): What changed in v3 and whether you need to act.

## Operations

- [Security](https://labs.vortex.nyc/convex-auth/security): Security controls in convex-auth: 2FA, CAPTCHA, breach checks, rate limits, sessions, and keys.
- [Production](https://labs.vortex.nyc/convex-auth/production): Ship convex-auth to production: env vars, check/preflight, deployment, and monitoring.
- [Testing](https://labs.vortex.nyc/convex-auth/testing): Helpers for driving the native auth flow in Convex unit tests.
- [Preflight](https://labs.vortex.nyc/convex-auth/preflight): Validate your auth setup before deploying.
- [Releasing](https://labs.vortex.nyc/convex-auth/releasing): How versions, changelogs, and releases ship: changesets, the release workflow, provenance, and versioned docs.
- [Troubleshooting](https://labs.vortex.nyc/convex-auth/troubleshooting): How to diagnose problems and report issues with @vortex-api/convex-auth.

## Internals

- [Per-feature components](https://labs.vortex.nyc/convex-auth/feature-gated-components): Install only the auth features you use — the component mount table.
- [Consumer contract](https://labs.vortex.nyc/convex-auth/consumer-contract): Public entrypoints and rules for using convex-auth in your own Convex project.
- [SSR auth contract](https://labs.vortex.nyc/convex-auth/ssr-contract): The framework-neutral spec every SSR adapter (Next.js, TanStack Start) satisfies.

## API

- [Convex Auth HTTP API](https://labs.vortex.nyc/convex-auth/api)

### Credentials

- [Alias of `/sign-in/email`](https://labs.vortex.nyc/convex-auth/api/credentials/sign-in)
- [Alias of `/sign-up/email`](https://labs.vortex.nyc/convex-auth/api/credentials/sign-up)
- [Create an account with email and password](https://labs.vortex.nyc/convex-auth/api/credentials/sign-up-email)
- [Request a password-reset email](https://labs.vortex.nyc/convex-auth/api/credentials/request-password-reset)
- [Sign in with email and password](https://labs.vortex.nyc/convex-auth/api/credentials/sign-in-email)

### OAuth

- [Begin an OAuth sign-in and return the provider authorization URL](https://labs.vortex.nyc/convex-auth/api/oauth/sign-in-social)
- [Begin an OAuth sign-in via a plain GET navigation](https://labs.vortex.nyc/convex-auth/api/oauth/signin-social-get)
- [OAuth provider callback (registered redirect URI)](https://labs.vortex.nyc/convex-auth/api/oauth/oauth-callback)

### OIDC

- [Exchange the session cookie for a short-lived Convex JWT](https://labs.vortex.nyc/convex-auth/api/oidc/convex-token)
- [Public keys for verifying Convex-auth JWTs](https://labs.vortex.nyc/convex-auth/api/oidc/convex-jwks)
- [Standard JWKS discovery path](https://labs.vortex.nyc/convex-auth/api/oidc/well-known-jwks)

### Session

- [Alias of `/session`](https://labs.vortex.nyc/convex-auth/api/session/get-session-alias)
- [Resolve the session cookie to a user](https://labs.vortex.nyc/convex-auth/api/session/get-session)
- [Revoke the session and clear cookies](https://labs.vortex.nyc/convex-auth/api/session/sign-out)
- [Rotate a refresh token into a new session pair](https://labs.vortex.nyc/convex-auth/api/session/update-session)

### Two-Factor

- [Begin TOTP enrollment](https://labs.vortex.nyc/convex-auth/api/two-factor/two-factor-enable)
- [Complete a challenge with a one-time backup code](https://labs.vortex.nyc/convex-auth/api/two-factor/two-factor-verify-backup-code)
- [Complete a TOTP challenge](https://labs.vortex.nyc/convex-auth/api/two-factor/two-factor-verify-totp)
- [Disable two-factor authentication](https://labs.vortex.nyc/convex-auth/api/two-factor/two-factor-disable)
- [Mint a fresh set of backup codes](https://labs.vortex.nyc/convex-auth/api/two-factor/two-factor-generate-backup-codes)

### Verification

- [Send an email-verification message](https://labs.vortex.nyc/convex-auth/api/verification/send-verification-email)
- [Validate a password-reset token and land on the app](https://labs.vortex.nyc/convex-auth/api/verification/reset-password-landing)
- [Verify a magic-link token and land on the app](https://labs.vortex.nyc/convex-auth/api/verification/magic-link-verify)
- [Verify an email address token](https://labs.vortex.nyc/convex-auth/api/verification/verify-email)

## Changelog

- [@vortex-api/convex-auth@3.0.1](https://labs.vortex.nyc/convex-auth/changelog/vortex-api-convex-auth-3-0-1)
- [v3.0.0](https://labs.vortex.nyc/convex-auth/changelog/v3-0-0)
- [convex-auth v2.5.2](https://labs.vortex.nyc/convex-auth/changelog/v2-5-2)
- [convex-auth v2.5.1](https://labs.vortex.nyc/convex-auth/changelog/v2-5-1)
- [convex-auth v2.4.1](https://labs.vortex.nyc/convex-auth/changelog/v2-4-1)
- [convex-auth v2.3.0](https://labs.vortex.nyc/convex-auth/changelog/v2-3-0)
- [convex-auth v2.0.5](https://labs.vortex.nyc/convex-auth/changelog/v2-0-5)
- [convex-auth v2.0.4](https://labs.vortex.nyc/convex-auth/changelog/v2-0-4)
- [convex-auth@1.7.5](https://labs.vortex.nyc/convex-auth/changelog/convex-auth-1-7-5)
- [convex-better-auth@2.0.5](https://labs.vortex.nyc/convex-auth/changelog/convex-better-auth-2-0-5)
- [convex-better-auth-adapter@0.13.4](https://labs.vortex.nyc/convex-auth/changelog/convex-better-auth-adapter-0-13-4)
- [convex-auth@1.7.2](https://labs.vortex.nyc/convex-auth/changelog/convex-auth-1-7-2)
- [convex-better-auth-adapter@0.13.3](https://labs.vortex.nyc/convex-auth/changelog/convex-better-auth-adapter-0-13-3)
- [convex-better-auth@2.0.3](https://labs.vortex.nyc/convex-auth/changelog/convex-better-auth-2-0-3)
- [convex-auth@1.7.0](https://labs.vortex.nyc/convex-auth/changelog/convex-auth-1-7-0)
- [convex-auth@1.7.1](https://labs.vortex.nyc/convex-auth/changelog/convex-auth-1-7-1)
- [convex-auth v0.1.0-alpha.0](https://labs.vortex.nyc/convex-auth/changelog/v0-1-0-alpha-0)

## RSS Feeds

- [Convex Auth — Changelog](https://labs.vortex.nyc/convex-auth/changelog/rss.xml)

## Agent resources

- [llms-full.txt](https://labs.vortex.nyc/convex-auth/llms-full.txt): The full Markdown of every page in one file.
- [Page Markdown](https://labs.vortex.nyc/convex-auth/index.md): Append `.md` to any page URL to fetch that page as raw Markdown.
- [JSON API](https://labs.vortex.nyc/convex-auth/api/docs/pages.json): Page index of the JSON docs API; each entry links the page's JSON and Markdown forms. Described by the OpenAPI document at https://labs.vortex.nyc/convex-auth/openapi.json.
- [API catalog](https://labs.vortex.nyc/convex-auth/.well-known/api-catalog): RFC 9727 linkset of the APIs documented here.
- [AI catalog](https://labs.vortex.nyc/convex-auth/.well-known/ai-catalog.json): ARD manifest of the agent-facing resources on this site (MCP server, skills, APIs).
- [agent-readability.json](https://labs.vortex.nyc/convex-auth/agent-readability.json): Manifest of every agent-facing artifact on this site.
- [Sitemap](https://labs.vortex.nyc/convex-auth/sitemap.xml): Every indexable page URL with its last-modified date.