---
title: Server API
description: Actions, queries, and HTTP routes re-exported by convexAuth.
sidebar:
  order: 16
---

`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

```ts convex/auth.ts
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

```ts convex/http.ts
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](/convex-auth/api). 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`:

```tsx
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`](/convex-auth/configuration) reference for every `convexAuth` option.
- Read the [`React client`](/convex-auth/react) guide for the hooks that call these actions.