Server API

Actions, queries, and HTTP routes re-exported by convexAuth.

convexAuth(config) returns Convex action, query, and HTTP route references. Re-export them from convex/auth.ts so Convex can see them and so the React client can call them via api.auth.

Expose the auth object

import { components } from "./_generated/api";
import { convexAuth } from "@vortex-api/convex-auth/convex";

export const auth = convexAuth({
  component: components.convexAuth,
  emailAndPassword: { enabled: true },
  oauth: {/* ... */},
});

export const {
  signUp,
  signIn,
  signOut,
  updateSession,
  sendEmailVerification,
  verifyEmail,
  sendPasswordReset,
  resetPassword,
  verifyPassword,
  changeEmail,
  twoFactorEnable,
  twoFactorVerifyTOTP,
  twoFactorVerifyBackupCode,
  twoFactorDisable,
  twoFactorGenerateBackupCodes,
} = auth;

Core actions

These are always present when emailAndPassword is enabled:

Action	Args (summary)	Returns
`signUp`	`{ email, password, name, image?, callbackURL?, rememberMe?, captchaToken? }`	Session (`nativeAuthSessionValidator`).
`signIn`	`{ email, password, callbackURL?, rememberMe?, trustedDeviceToken? }`	Session or two-factor challenge.
`signOut`	`{ token, callbackURL? }`	`{ success, redirect?, url? }`
`updateSession`	`{ refreshToken }`	Rotates the session and returns the new pair.
`sendEmailVerification`	`{ email, callbackURL? }`	`EmailSendResult` (`{ status, reason?, emailId? }`).
`verifyEmail`	`{ token }`	`{ success, reason? }`.
`sendPasswordReset`	`{ email, redirectTo?, captchaToken? }`	`EmailSendResult`.
`resetPassword`	`{ token, newPassword }`	`{ status, reason? }`.
`verifyPassword`	`{ token, password }`	`{ success }`.
`updateUser`	`{ token, name?, image?, metadataJson? }`	`{ success, error? }`.
`listSessions`	`{ token }`	Active sessions (`{ id, isCurrent, userId, expiresAt, ipAddress?, userAgent?, createdAt, updatedAt }[]`).
`revokeSession`	`{ token, sessionId }`	`{ success }` — revokes the session’s rotation family.
`revokeOtherSessions`	`{ token }`	`{ success }` — revokes all sessions except the current family.
`twoFactorEnable`	`{ token, password, issuer? }`	`{ token?, totpURI?, backupCodes?, error? }`.
`twoFactorVerifyTOTP`	`{ token, code, trustDevice? }`	Session (`nativeAuthSessionValidator`).
`twoFactorVerifyBackupCode`	`{ token, code, trustDevice? }`	Session (`nativeAuthSessionValidator`).
`twoFactorDisable`	`{ token, password }`	`{ success }`.
`twoFactorGenerateBackupCodes`	`{ token, password }`	`{ backupCodes, error? }`.

signIn returns a session by default. If the user has 2FA enabled, it returns a twoFactorChallengeToken instead.

OAuth actions

Present when oauth is configured:

Action	Args	Returns
`signInWithRedirect`	`{ provider, callbackURL?, errorURL?, newUserURL?, requestSignUp?, link?, landingVerifier? }`	`{ url }` to redirect the browser.
`callback`	`{ provider, code, state, linkingUserId?, landingVerifier? }`	Session, or `{ error, errorDescription?, redirectUrl }`.

The callback action is also exposed as an HTTP route by auth.addHttpRoutes(http). The browser usually completes OAuth through the HTTP callback rather than calling callback from the client.

Email change is not a separate action — send a change OTP with sendVerificationOtp({ email, type: "change-email" }) when emailOtp is configured.

Magic link actions

Present when magicLink is configured:

Action	Args (summary)	Returns
`signInMagicLink`	`{ email, name?, callbackURL?, newUserCallbackURL?, errorCallbackURL?, metadata? }`	`EmailSendResult`
`verifyMagicLink`	`{ token, callbackURL? }`	Session.

verifyMagicLink is exposed as GET /api/auth/magic-link/verify by addHttpRoutes.

Email OTP actions

Present when emailOtp is configured:

Action	Args (summary)	Returns
`sendVerificationOtp`	`{ email, type?, name? }`	`EmailSendResult`.
`verifyEmailOtp`	`{ email, otp, type?, newPassword? }`	Session, verify, reset, or change result.

Queries

convexAuth always re-exports these queries (they do not depend on which providers are enabled):

Query	Args	Returns
`isAuthenticated`	none	`boolean`
`verifySession`	`{ token? }`	`{ user?, sessionId? }` if the token is valid.

HTTP routes

import { httpRouter } from "convex/server";
import { auth } from "./auth";

const http = httpRouter();
auth.addHttpRoutes(http);

export default http;

addHttpRoutes mounts the routes that handle browser redirects and email links:

Route	Purpose
`GET /api/auth/verify-email`	Confirm an email-verification token.
`GET /api/auth/reset-password/:token`	Validate a password-reset token.
`GET /api/auth/magic-link/verify`	Validate a magic link and issue a session.
`GET /api/auth/callback/:provider`	OAuth provider callback.

The full wire contract — every route, request field, response shape, and error reason — is maintained as an OpenAPI document and rendered at API Reference. The spec is the source of truth; this table is the overview.

Calling actions from the client

Once re-exported, the actions are available as api.auth.* and can be called with useAction:

import { useAction } from "convex/react";
import { api } from "../convex/_generated/api";

function OAuthButton(props: { provider: "google" | "github" | "discord" }) {
  const start = useAction(api.auth.signInWithRedirect);

  async function onClick() {
    const { url } = await start({
      provider: props.provider,
      callbackURL: `${window.location.origin}/auth/callback`,
    });
    window.location.href = url;
  }

  return <button onClick={onClick}>Sign in with {props.provider}</button>;
}

Next steps

Read the Configuration reference for every convexAuth option.
Read the React client guide for the hooks that call these actions.