---
seo:
  description: >-
    The HTTP surface served by the convex-auth component at
    https://<your-deployment>.convex.site. Browser clients consume it through
    cookies; SSR adapters…
sidebar:
  label: Overview
title: Convex Auth HTTP API
---
The HTTP surface served by the `convex-auth` component at
`https://<your-deployment>.convex.site`. Browser clients consume it
through cookies; SSR adapters (Next.js, TanStack Start) proxy it on the
app's own origin; React Native and token-mode clients consume it
directly with bearer tokens.

Redirect-bearing parameters (`callbackURL`, `errorURL`, `newUserURL`,
`newUserCallbackURL`, `errorCallbackURL`, `redirectTo`) are validated
against `SITE_URL`/`CONVEX_SITE_URL` plus any configured
`trustedOrigins`. Untrusted values are rejected with a 400 or an error
redirect — never silently followed.

Endpoints that write session cookies enforce CSRF via Fetch Metadata /
Origin checks; cross-site POSTs are rejected with 403.

Version 2.5.2

Base URL: `https://{deployment}.convex.site`

## Session

Read, rotate, and destroy sessions.

- [`GET /api/auth/session`](/api/session/get-session) — Resolve the session cookie to a user.
- [`GET /api/auth/get-session`](/api/session/get-session-alias) — Alias of \`/session\`.
- [`POST /api/auth/update-session`](/api/session/update-session) — Rotate a refresh token into a new session pair.
- [`POST /api/auth/sign-out`](/api/session/sign-out) — Revoke the session and clear cookies.

## Credentials

Email/password sign-up, sign-in, and password reset.

- [`POST /api/auth/sign-up/email`](/api/credentials/sign-up-email) — Create an account with email and password.
- [`POST /api/auth/sign-in/email`](/api/credentials/sign-in-email) — Sign in with email and password.
- [`POST /api/auth/sign-in`](/api/credentials/sign-in) — Alias of \`/sign-in/email\`.
- [`POST /api/auth/sign-up`](/api/credentials/sign-up) — Alias of \`/sign-up/email\`.
- [`POST /api/auth/request-password-reset`](/api/credentials/request-password-reset) — Request a password-reset email.

## OAuth

Social sign-in initiation and provider callbacks.

- [`POST /api/auth/sign-in/social`](/api/oauth/sign-in-social) — Begin an OAuth sign-in and return the provider authorization URL.
- [`GET /api/auth/signin/{provider}`](/api/oauth/signin-social-get) — Begin an OAuth sign-in via a plain GET navigation.
- [`GET /api/auth/callback/{provider}`](/api/oauth/oauth-callback) — OAuth provider callback (registered redirect URI).

## Verification

Email verification and magic-link landings.

- [`GET /api/auth/magic-link/verify`](/api/verification/magic-link-verify) — Verify a magic-link token and land on the app.
- [`GET /api/auth/reset-password/{token}`](/api/verification/reset-password-landing) — Validate a password-reset token and land on the app.
- [`GET /api/auth/verify-email`](/api/verification/verify-email) — Verify an email address token.
- [`POST /api/auth/send-verification-email`](/api/verification/send-verification-email) — Send an email-verification message.

## Two-Factor

TOTP enrollment, challenge, and backup codes.

- [`POST /api/auth/two-factor/enable`](/api/two-factor/two-factor-enable) — Begin TOTP enrollment.
- [`POST /api/auth/two-factor/verify-totp`](/api/two-factor/two-factor-verify-totp) — Complete a TOTP challenge.
- [`POST /api/auth/two-factor/verify-backup-code`](/api/two-factor/two-factor-verify-backup-code) — Complete a challenge with a one-time backup code.
- [`POST /api/auth/two-factor/disable`](/api/two-factor/two-factor-disable) — Disable two-factor authentication.
- [`POST /api/auth/two-factor/generate-backup-codes`](/api/two-factor/two-factor-generate-backup-codes) — Mint a fresh set of backup codes.

## OIDC

JWT/JWKS material for `ctx.auth.getUserIdentity()`.

- [`GET /api/auth/convex/jwks`](/api/oidc/convex-jwks) — Public keys for verifying Convex-auth JWTs.
- [`GET /.well-known/jwks.json`](/api/oidc/well-known-jwks) — Standard JWKS discovery path.
- [`GET /api/auth/convex/token`](/api/oidc/convex-token) — Exchange the session cookie for a short-lived Convex JWT.