Convex Auth

https://labs.convex.dev/auth
Admin
Convex Auth is a library for implementing authentication directly within your Convex backend,...
Tokens:46,321
Snippets:403
Trust Score:9.9
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install @convex-dev/auth and @auth/core

Source: https://labs.convex.dev/auth/setup

Installs the Convex Auth library and the Auth.js core package, which is used for provider configuration later.

```bash
npm install @convex-dev/auth @auth/core@0.41.1
```

--------------------------------

### ConvexCredentials provider setup example

Source: https://labs.convex.dev/auth/api_reference/providers/ConvexCredentials

Shows how to configure the ConvexCredentials provider with a custom authorize function. The authorize function receives credentials and context, and should return a user ID or null. This is for custom authentication; often the Password provider is simpler.

```typescript
import { ConvexCredentials } from "@convex-dev/auth/providers/ConvexCredentials";
import { convexAuth } from "@convex-dev/auth/server";
 
export const { auth, signIn, signOut, store, isAuthenticated } = convexAuth({
  providers: [
    ConvexCredentials({
      authorize: async (credentials, ctx) => {
        // Your custom logic here...
      },
    }),
  ],
});
```

--------------------------------

### GitHub OAuth callback URL example

Source: https://labs.convex.dev/auth/config/oauth/github

The Authorization callback URL is your Convex HTTP Actions URL plus '/api/auth/callback/github'. Replace the example domain with your own deployment's actions URL.

```text
https://fast-horse-123.convex.site/api/auth/callback/github
```

--------------------------------

### beforeSessionCreation callback example

Source: https://labs.convex.dev/auth/api_reference/server

Example of using the beforeSessionCreation callback to reject sign-in for banned users. Throws an error if the user's 'banned' field is truthy.

```typescript
callbacks: {
  async beforeSessionCreation(ctx, { userId }) {
    const user = await ctx.db.get(userId);
    if (user?.banned) {
      throw new Error("Account is banned");
    }
  },
}
```

--------------------------------

### Create a new Convex project with npm create convex@latest

Source: https://labs.convex.dev/auth/setup

Run this command to start a new project from scratch. Choose 'React (Vite)' and then 'Convex Auth' when prompted.

```bash
npm create convex@latest
```

--------------------------------

### Initialize production environment variables with npx @convex-dev/auth --prod

Source: https://labs.convex.dev/auth/production

Run this command from your project directory to configure the minimal set of required environment variables on your production deployment. It assumes your prod deployment is in the same project as your dev deployment; if not, follow the first two steps from Manual Setup.

```bash
npx @convex-dev/auth --prod

```

--------------------------------

### Configure Anonymous provider with convexAuth

Source: https://labs.convex.dev/auth/api_reference/providers/Anonymous

Imports the Anonymous provider and convexAuth, then configures the auth with the Anonymous provider. This is the standard setup for enabling anonymous authentication.

```typescript
import { Anonymous } from "@convex-dev/auth/providers/Anonymous";
import { convexAuth } from "@convex-dev/auth/server";
 
export const { auth, signIn, signOut, store, isAuthenticated } = convexAuth({
  providers: [Anonymous],
});
```

--------------------------------

### convexAuthNextjsMiddleware handler with authentication check

Source: https://labs.convex.dev/auth/api_reference/nextjs/server

Example of using the ConvexAuthNextjsMiddlewareContext to check authentication and redirect unauthenticated users to /login. The context provides getToken and isAuthenticated methods as alternatives to convexAuthNextjsToken and isAuthenticatedNextjs.

```javascript
export function convexAuthNextjsMiddleware(handler, options) {
  return async (request, event, convexAuth) => {
    if (!(await convexAuth.isAuthenticated())) {
      return nextjsMiddlewareRedirect(request, "/login");
    }
  };
}
```

--------------------------------

### ConvexAuthNextjsMiddlewareContext

Source: https://labs.convex.dev/auth/api_reference/nextjs/server

Provides methods to get the token and check authentication status within convexAuthNextjsMiddleware, as an alternative to convexAuthNextjsToken and isAuthenticatedNextjs.

```APIDOC
## ConvexAuthNextjsMiddlewareContext

### Description
In `convexAuthNextjsMiddleware`, you can use this context to get the token and check if the client is authenticated in place of `convexAuthNextjsToken` and `isAuthenticatedNextjs`.

### Methods

#### getToken()
Returns `Promise<string | undefined>`

#### isAuthenticated()
Returns `Promise<boolean>`

### Defined in
src/nextjs/server/index.tsx:135
```

--------------------------------

### Configure Email provider with authorize undefined for magic link behavior

Source: https://labs.convex.dev/auth/api_reference/providers/Email

This example shows how to configure the Email provider to skip the email check during token verification, enabling 'magic link behavior' where only the token is needed. It imports `Email` from `@convex-dev/auth/providers/Email` and `convexAuth` from `@convex-dev/auth/server`, then passes `Email({ authorize: undefined })` to the providers array.

```typescript
import { Email } from "@convex-dev/auth/providers/Email";
import { convexAuth } from "@convex-dev/auth/server";
 
export const { auth, signIn, signOut, store, isAuthenticated } = convexAuth({
  providers: [
    Email({ authorize: undefined }),
  ],
});
```

--------------------------------

### Create custom Resend OTP provider (convex/ResendOTP.ts)

Source: https://labs.convex.dev/auth/config/passwords

Defines a custom Auth.js email provider using Resend to send OTP codes. Requires installing 'resend' and '@oslojs/crypto' via 'npm i resend @oslojs/crypto'. Uses the AUTH_RESEND_KEY environment variable for the API key and generates an 8-digit numeric code.

```TypeScript
import Resend from "@auth/core/providers/resend";
import { Resend as ResendAPI } from "resend";
import { RandomReader, generateRandomString } from "@oslojs/crypto/random";
 
export const ResendOTP = Resend({
  id: "resend-otp",
  apiKey: process.env.AUTH_RESEND_KEY,
  async generateVerificationToken() {
    const random: RandomReader = {
      read(bytes) {
        crypto.getRandomValues(bytes);
      },
    };
 
    const alphabet = "0123456789";
    const length = 8;
    return generateRandomString(random, alphabet, length);
  },
  async sendVerificationRequest({ identifier: email, provider, token }) {
    const resend = new ResendAPI(provider.apiKey);
    const { error } = await resend.emails.send({
      from: "My App <onboarding@resend.dev>",
      to: [email],
      subject: `Sign in to My App`,
      text: "Your code is " + token,
    });
 
    if (error) {
      throw new Error("Could not send");
    }
  },
});
```

--------------------------------

### Run the Convex Auth initialization command

Source: https://labs.convex.dev/auth/setup

Sets up your project for authenticating via the library. Alternatively, you can perform the steps manually.

```bash
npx @convex-dev/auth
```

--------------------------------

### Authenticate HTTP actions with useAuthToken

Source: https://labs.convex.dev/auth/authz

Use the `useAuthToken` hook from `@convex-dev/auth/react` to get the JWT token for authenticating HTTP requests. The example shows a fetch call with an `Authorization: Bearer` header, and notes you might need to set up `VITE_CONVEX_SITE_URL`.

```tsx
import { useAuthToken } from "@convex-dev/auth/react";
 
function SomeComponent() {
  const token = useAuthToken();
  const onClick = async () => {
    // You might need to set up `VITE_CONVEX_SITE_URL`
    const response = await fetch(
      `${process.env.VITE_CONVEX_SITE_URL!}/someEndpoint`,
      { headers: { Authorization: `Bearer ${token}` } }
    );
    // ...
  };
  // ...
}
```

--------------------------------

### useAuthToken() usage in a React component

Source: https://labs.convex.dev/auth/api_reference/react

Use this hook to get the JWT token on the client. The token should not be passed to other servers; treat it as an ID token. The example shows using the token in an Authorization header for a fetch request to a Convex HTTP action.

```javascript
import { useAuthToken } from "@convex-dev/auth/react";
 
function SomeComponent() {
  const token = useAuthToken();
  const onClick = async () => {
    await fetch(`${CONVEX_SITE_URL}/someEndpoint`, {
      headers: {
        Authorization: `Bearer ${token}`,
      },
    });
  };
  // ...
}
```

--------------------------------

### React/Next.js Client: shouldHandleCode with ConvexAuthProvider

Source: https://labs.convex.dev/auth/advanced

Provide `shouldHandleCode` as a prop to `ConvexAuthProvider` in React or Next.js client components. The function returns a boolean; returning `false` prevents Convex Auth from handling the `code` parameter. The example skips handling on paths starting with `/auth`.

```tsx
import { ConvexAuthProvider } from "@convex-dev/auth/react";
 
<ConvexAuthProvider
  client={convex}
  shouldHandleCode={() => {
    // Skip handling code parameter on specific paths
    return location.pathname.startsWith("/auth");
  }}
>
  {children}
</ConvexAuthProvider>;
```

--------------------------------

### Set SITE_URL environment variable

Source: https://labs.convex.dev/auth/setup/manual

Sets the SITE_URL environment variable for local development. Adjust the port number as needed.

```bash
npx convex env set SITE_URL http://localhost:5173
```

--------------------------------

### Get current session ID with getAuthSessionId

Source: https://labs.convex.dev/auth/authz

Call `getAuthSessionId` from `@convex-dev/auth/server` in a query, mutation, or action to get the session ID. Returns `Doc<"authSessions">` or `null` when unauthenticated.

```tsx
import { getAuthSessionId } from "@convex-dev/auth/server";
import { query } from "./_generated/server";
 
export const currentSession = query({
  args: {},
  handler: async (ctx) => {
    const sessionId = await getAuthSessionId(ctx);
    if (sessionId === null) {
      return null;
    }
    return await ctx.db.get(sessionId);
  },
});
```

--------------------------------

### Get currently signed-in user ID with getAuthUserId

Source: https://labs.convex.dev/auth/authz

Call `getAuthUserId` from `@convex-dev/auth/server` in a query, mutation, or action to get the user ID. Returns `Doc<"users">` or `null` when unauthenticated.

```tsx
import { getAuthUserId } from "@convex-dev/auth/server";
import { query } from "./_generated/server";
 
export const currentUser = query({
  args: {},
  handler: async (ctx) => {
    const userId = await getAuthUserId(ctx);
    if (userId === null) {
      return null;
    }
    return await ctx.db.get(userId);
  },
});
```

--------------------------------

### Set up React provider with ConvexAuthProvider

Source: https://labs.convex.dev/auth/setup

Replace ConvexProvider from convex/react with ConvexAuthProvider from @convex-dev/auth/react in your main entry file.

```typescript
import { ConvexAuthProvider } from "@convex-dev/auth/react";
import React from "react";
import ReactDOM from "react-dom/client";
import { ConvexReactClient } from "convex/react";
import App from "./App.tsx";
import "./index.css";
 
const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);
 
ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <ConvexAuthProvider client={convex}>
      <App />
    </ConvexAuthProvider>
  </React.StrictMode>,
);
```

--------------------------------

### Password()

Source: https://labs.convex.dev/auth/api_reference/providers/Password

Creates a Password provider instance with the given configuration. Passwords are hashed using Scrypt by default, customizable via the crypto option.

```APIDOC
## Password()

### Description
Email and password authentication provider. Passwords are by default hashed using Scrypt from Lucia. You can customize the hashing via the `crypto` option. Email verification is not required unless you pass an email provider to the `verify` option.

### Parameters
- `config` (PasswordConfig<DataModel>) - Required - Configuration object for the Password provider.

### Returns
`ConvexCredentialsConfig`

### Defined in
src/providers/Password.ts:115
```

--------------------------------

### getAuthUserId() usage in a Convex mutation

Source: https://labs.convex.dev/auth/api_reference/server

Example mutation that uses getAuthUserId(ctx) to retrieve the signed-in user's ID. Throws an error if the client is not authenticated (userId is null). The example is from convex/myFunctions.tsx and imports getAuthUserId from @convex-dev/auth/server.

```TypeScript
import { mutation } from "./_generated/server";
import { getAuthUserId } from "@convex-dev/auth/server";
 
export const doSomething = mutation({
  args: {/* ... */},
  handler: async (ctx, args) => {
    const userId = await getAuthUserId(ctx);
    if (userId === null) {
      throw new Error("Client is not authenticated!")
    }
    const user = await ctx.db.get(userId);
    // ...
  },
});
```

--------------------------------

### createAccount(ctx, args)

Source: https://labs.convex.dev/auth/api_reference/server

Creates an account and a user with a unique account ID. Use this from a ConvexCredentials provider to create a new user account.

```APIDOC
## createAccount(ctx, args)

### Description
Creates an account and a user with a unique account ID. Use this from a ConvexCredentials provider to create a new user account.

### Parameters
- `ctx` (GenericActionCtx<DataModel>) - Required - The action context.
- `args` (object) - Required - The arguments object.
  - `args.provider` (string) - Required - The provider ID (like "password"), used to disambiguate accounts. It is also used to configure account secret hashing via the provider's `crypto` option.
  - `args.account` (object) - Required - The account object.
    - `args.account.id` (string) - Required - The unique external ID for the account, for example email address.
    - `args.account.secret` (string) - Optional - The secret credential to store for this account, if given.
  - `args.profile` (WithoutSystemFields<DocumentByName<DataModel, "users">>) - Required - The profile data to store for the user. These must fit the `users` table schema.
  - `args.shouldLinkViaEmail` (boolean) - Optional - If `true`, the account will be linked to an existing user with the same verified email address. This is only safe if the returned account's email is verified before the user is allowed to sign in with it.
  - `args.shouldLinkViaPhone` (boolean) - Optional - If `true`, the account will be linked to an existing user with the same verified phone number. This is only safe if the returned account's phone is verified before the user is allowed to sign in with it.

### Returns
- `Promise<object>` - An object containing the user ID if it successfully creates the account, or throws an error.
  - `account` - The created account.
  - `user` - The created user.
```

--------------------------------

### convexAuth(config)

Source: https://labs.convex.dev/auth/api_reference/server

The main entry point for the Convex Auth server library. It accepts a `ConvexAuthConfig` object and returns an object with `auth`, `signIn`, `signOut`, `store`, and optionally `isAuthenticated` functions.

```APIDOC
## convexAuth(config)

### Description
Initializes Convex Auth with the provided configuration. Returns an object containing authentication helpers (`auth`, `signIn`, `signOut`, `store`, and optionally `isAuthenticated`).

### Parameters
- **config** (`ConvexAuthConfig`) - Required - The configuration object for Convex Auth.

### Returns
An object with the following properties:
- `auth` - Authentication helper.
- `signIn` - Sign-in helper.
- `signOut` - Sign-out helper.
- `store` - Storage helper.
- `isAuthenticated` - (optional) Authentication check helper.

### Example
```ts
import { convexAuth } from "@convex-dev/auth/server";
import GitHub from "@auth/core/providers/github";

export const { auth, signIn, signOut, store, isAuthenticated } = convexAuth({
  providers: [GitHub],
});
```
```

--------------------------------

### Sign out with useAuthActions in React

Source: https://labs.convex.dev/auth/authz

Use the `signOut` function from `@convex-dev/auth/react` to sign the user out. The example shows a button that calls `signOut`.

```tsx
import { useAuthActions } from "@convex-dev/auth/react";
 
export function SignOut() {
  const { signOut } = useAuthActions();
  return <button onClick={() => void signOut()}>Sign out</button>;
}
```

--------------------------------

### nextjsMiddlewareRedirect helper function

Source: https://labs.convex.dev/auth/authz/nextjs

This is the implementation of `nextjsMiddlewareRedirect`, a shortcut for creating a redirect response. It clones the request URL, sets the pathname, and returns a `NextResponse.redirect`. You can inline this code if you need more control over the target URL.

```TypeScript
export function nextjsMiddlewareRedirect(
  request: NextRequest,
  pathname: string,
) {
  const url = request.nextUrl.clone();
  url.pathname = pathname;
  return NextResponse.redirect(url);
}
```

--------------------------------

### getAuthUserId(ctx)

Source: https://labs.convex.dev/auth/api_reference/server

Returns the currently signed-in user's ID. Use this in a mutation or action to get the user ID, or null if the client is not authenticated.

```APIDOC
## getAuthUserId(ctx)

### Description
Returns the currently signed-in user's ID. Use this in a mutation or action to get the user ID, or null if the client is not authenticated.

### Parameters
- `ctx` (object) - Required - The query, mutation, or action context.
- `ctx.auth` (Auth) - Required - The authentication object.

### Returns
- `Promise<null | Id<"users">>` - The user ID or `null` if the client isn't authenticated.

### Example
```ts
import { mutation } from "./_generated/server";
import { getAuthUserId } from "@convex-dev/auth/server";

export const doSomething = mutation({
  args: {/* ... */},
  handler: async (ctx, args) => {
    const userId = await getAuthUserId(ctx);
    if (userId === null) {
      throw new Error("Client is not authenticated!")
    }
    const user = await ctx.db.get(userId);
    // ...
  },
});
```
```

--------------------------------

### callbacks.beforeSessionCreation()

Source: https://labs.convex.dev/auth/api_reference/server

Called before a new session is created for a user. This callback runs during every sign-in flow (credentials, OAuth, email, phone) right before the session is persisted. Throw an error to reject the sign-in.

```APIDOC
## callbacks.beforeSessionCreation()

### Description
Called before a new session is created for a user. This callback runs during every sign-in flow (credentials, OAuth, email, phone) right before the session is persisted. Throw an error to reject the sign-in. This is useful for checking whether a user is banned or otherwise disallowed from signing in.

### Parameters

#### ctx
- **Type**: `GenericMutationCtx<AnyDataModel>`
- **Required**: Yes
- **Description**: The Convex mutation context.

#### args
- **Type**: `object`
- **Required**: Yes
- **Description**: The arguments object.

#### args.userId
- **Type**: `GenericId<"users">`
- **Required**: Yes
- **Description**: The ID of the user about to be signed in.

### Returns
- **Type**: `Promise<void>`
- **Description**: A promise that resolves when the callback completes.
```

--------------------------------

### Set AUTH_RESEND_KEY environment variable

Source: https://labs.convex.dev/auth/config/email

Run this command to set the Resend API key as an environment variable on your Convex backend. Replace 'yourresendkey' with your actual key. Also ensure SITE_URL has the correct port number.

```bash
npx convex env set AUTH_RESEND_KEY yourresendkey
```

--------------------------------

### Reading custom claims in a query (convex/myFunctions.ts)

Source: https://labs.convex.dev/auth/advanced

Read the custom claims in any query, mutation, or action using ctx.auth.getUserIdentity(). This example returns the role claim from the identity.

```typescript
import { query } from "./_generated/server";
 
export const currentUserRole = query({
  args: {},
  handler: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    return identity?.role;
  },
});
```

--------------------------------

### Configure convex/http.ts

Source: https://labs.convex.dev/auth/setup/manual

Sets up the HTTP router and adds the auth routes.

```typescript
import { httpRouter } from "convex/server";
import { auth } from "./auth";
 
const http = httpRouter();
 
auth.addHttpRoutes(http);
 
export default http;
```

--------------------------------

### Phone()

Source: https://labs.convex.dev/auth/api_reference/providers/Phone

Creates a phone provider configuration that sends a verification token to the user's phone number. It validates that the phone field in the token matches the phone used during sign-in.

```APIDOC
## Phone()

### Description
Phone providers send a token to the user's phone number for sign-in. When you use this function to create your config, it checks that there is a `phone` field during token verification that matches the `phone` used during the initial `signIn` call.

### Parameters
| Parameter | Type |
|-----------|------|
| `config` | `PhoneUserConfig` & `Pick<PhoneConfig<GenericDataModel>, "sendVerificationRequest">` |

### Returns
`PhoneConfig<DataModel>`

### Defined in
src/providers/Phone.ts:23
```

--------------------------------

### Email()

Source: https://labs.convex.dev/auth/api_reference/providers/Email

Creates an email provider configuration. It sends a token to the user's email for sign-in and by default checks that the email field matches during token verification. You can override the authorize method to skip this check for magic link behavior.

```APIDOC
## Email()

### Description
Email providers send a token to the user's email address for sign-in. When you use this function to create your config, by default it checks that there is an `email` field during token verification that matches the `email` used during the initial `signIn` call. If you want the "magic link behavior", where only the token is needed, you can override the `authorize` method to skip the check.

### Parameters
| Parameter | Type |
|-----------|------|
| `config` | `EmailUserConfig<DataModel> & Pick<EmailConfig<GenericDataModel>, "sendVerificationRequest">` |

### Returns
`EmailConfig<DataModel>`

### Defined in
src/providers/Email.ts:34

### Example
```
import { Email } from "@convex-dev/auth/providers/Email";
import { convexAuth } from "@convex-dev/auth/server";
 
export const { auth, signIn, signOut, store, isAuthenticated } = convexAuth({
  providers: [
    Email({ authorize: undefined }),
  ],
});
```

### Notes
Make sure the token has high enough entropy to be secure.
```

--------------------------------

### useAuthActions() hook usage

Source: https://labs.convex.dev/auth/api_reference/react

Use this hook to access the signIn and signOut methods. Import useAuthActions from "@convex-dev/auth/react" and call it inside a component to get the signIn and signOut functions.

```typescript
import { useAuthActions } from "@convex-dev/auth/react";
 
function SomeComponent() {
  const { signIn, signOut } = useAuthActions();
  // ...
}
```

--------------------------------

### GitHub Sign-In Button in React

Source: https://labs.convex.dev/auth/config/oauth

Example of a React component that triggers the OAuth sign-in flow for GitHub using the signIn function from useAuthActions. The provider ID is 'github', which is the lowercase version of the provider name.

```tsx
import { useAuthActions } from "@convex-dev/auth/react";
 
export function SignIn() {
  const { signIn } = useAuthActions();
  return (
    <button onClick={() => void signIn("github")}>Sign in with GitHub</button>
  );
}
```

--------------------------------

### nextjsMiddlewareRedirect redirect with query params

Source: https://labs.convex.dev/auth/api_reference/nextjs/server

Redirects to a route with query parameters, useful for preserving the intended destination after login.

```typescript
return nextjsMiddlewareRedirect(request, "/login?next=/app/dashboard");
```

--------------------------------

### Next.js Middleware: shouldHandleCode with convexAuthNextjsMiddleware

Source: https://labs.convex.dev/auth/advanced

In Next.js middleware, `shouldHandleCode` is an option to `convexAuthNextjsMiddleware`. The function receives the request object and can be async. The example skips handling for the Figma OAuth callback path and handles all other code parameters.

```ts
export default convexAuthNextjsMiddleware(
  (request, { convexAuth }) => {
    // ... route protection logic
  },
  {
    shouldHandleCode: (request) => {
      // Skip handling code parameter for Figma OAuth callback
      if (
        request.nextUrl.pathname.startsWith(
          "/settings/profile/figma-auth-callback",
        )
      ) {
        return false;
      }
      // Handle all other code parameters
      return true;
    },
  },
);
```

--------------------------------

### Configure OAuth provider as untrusted with allowDangerousEmailAccountLinking

Source: https://labs.convex.dev/auth/advanced

Sets the allowDangerousEmailAccountLinking option to false for the GitHub provider, making it untrusted. This prevents automatic account linking for this provider. The example shows the convexAuth configuration with Resend and GitHub providers.

```TypeScript
import Resend from "@auth/core/providers/resend";
import GitHub from "@auth/core/providers/github";
import { convexAuth } from "@convex-dev/auth/server";
 
export const { auth, signIn, signOut, store, isAuthenticated } =
  convexAuth({
    providers: [
      Resend,
      GitHub({ allowDangerousEmailAccountLinking: false }),
    ],
  });
```

--------------------------------

### getAuthSessionId() usage in a Convex mutation

Source: https://labs.convex.dev/auth/api_reference/server

Example of using getAuthSessionId(ctx) inside a mutation to retrieve the current session ID. Throws an error if the client is not authenticated (sessionId is null). The session ID can then be used to fetch the session document from the database.

```TypeScript
import { mutation } from "./_generated/server";
import { getAuthSessionId } from "@convex-dev/auth/server";
 
export const doSomething = mutation({
  args: {/* ... */},
  handler: async (ctx, args) => {
    const sessionId = await getAuthSessionId(ctx);
    if (sessionId === null) {
      throw new Error("Client is not authenticated!")
    }
    const session = await ctx.db.get(sessionId);
    // ...
  },
});
```

--------------------------------

### Import and configure Password provider

Source: https://labs.convex.dev/auth/api_reference/providers/Password

Sets up the Password provider with convexAuth. The provider supports flows: signUp, signIn, reset, reset-verification, and email-verification.

```typescript
import { Password } from "@convex-dev/auth/providers/Password";
import { convexAuth } from "@convex-dev/auth/server";
 
export const { auth, signIn, signOut, store, isAuthenticated } = convexAuth({
  providers: [Password],
});
```

--------------------------------

### Call authenticated mutations and actions with fetchMutation and convexAuthNextjsToken

Source: https://labs.convex.dev/auth/authz/nextjs

Use fetchMutation from convex/nextjs and convexAuthNextjsToken to call authenticated mutations from Next.js Server Actions. The token is passed as an option to fetchMutation. Security notice: avoid side-effects on GET requests to prevent CSRF attacks.

```typescript
import { convexAuthNextjsToken } from "@convex-dev/auth/nextjs/server";
import { api } from "@/convex/_generated/api";
import { fetchMutation, fetchQuery } from "convex/nextjs";
import { revalidatePath } from "next/cache";
 
export default async function PureServerPage() {
  const tasks = await fetchQuery(api.tasks.list, { list: "default" });
  async function createTask(formData: FormData) {
    "use server";
 
    await fetchMutation(
      api.tasks.create,
      {
        text: formData.get("text") as string,
      },
      { token: await convexAuthNextjsToken() },
    );
    revalidatePath("/example");
  }
  // render tasks and task creation form
  return <form action={createTask}>...</form>;
}
```

--------------------------------

### Custom createOrUpdateUser callback for user creation and account linking

Source: https://labs.convex.dev/auth/advanced

Provides a custom createOrUpdateUser callback to control user creation and account linking. When provided, the library does not create or update users automatically; all logic must be implemented. The callback receives args with type and provider information, and can use existingUserId, profile, and ctx to implement custom behavior.

```TypeScript
import GitHub from "@auth/core/providers/github";
import { Password } from "@convex-dev/auth/providers/Password";
import { MutationCtx } from "./_generated/server";
 
export const { auth, signIn, signOut, store, isAuthenticated } = {
  providers: [GitHub, Password],
  callbacks: {
    // `args.type` is one of "oauth" | "email" | "phone" | "credentials" | "verification"
    // `args.provider` is the currently used provider config
    async createOrUpdateUser(ctx: MutationCtx, args) {
      if (args.existingUserId) {
        // Optionally merge updated fields into the existing user object here
        return args.existingUserId;
      }
 
      // Implement your own account linking logic:
      const existingUser = await findUserByEmail(ctx, args.profile.email);
      if (existingUser) return existingUser._id;
 
      // Implement your own user creation:
      return ctx.db.insert("users", {
        /* ... */
      });
    },
  },
};
```

--------------------------------

### convexAuth()

Source: https://labs.convex.dev/auth/api_reference/server

Configures the Convex Auth library. Returns an object with functions and an auth helper. You must export the functions from convex/auth.ts to make them callable.

```APIDOC
## convexAuth()

### Description
Configure the Convex Auth library. Returns an object with functions and `auth` helper. You must export the functions from `convex/auth.ts` to make them callable.

### Parameters
- `config_` (ConvexAuthConfig) - Required - Configuration for authentication methods.

### Returns
An object with fields you should reexport from your `convex/auth.ts` file.

#### auth
Helper for configuring HTTP actions.

##### auth.addHttpRoutes()
Add HTTP actions for JWT verification and OAuth sign-in.

###### Parameters
- `http` (HttpRouter) - Required - Your HTTP router.

###### Returns
`void`

###### Routes Handled
- Always: `/.well-known/openid-configuration`, `/.well-known/jwks.json`
- If OAuth is configured: `/api/auth/signin/*`, `/api/auth/callback/*`

#### signIn
Action called by the client to sign the user in. Also used for refreshing the session.

#### signOut
Action called by the client to invalidate the current session.

#### store
Internal mutation used by the library to read and write to the database during signin and signout.

#### isAuthenticated
Utility function for frameworks to use to get the current auth state based on credentials that they've supplied separately.

### Example
```ts
import { convexAuth } from "@convex-dev/auth/server";

export const { auth, signIn, signOut, store, isAuthenticated } = convexAuth({
  providers: [],
});
```

### Example: Adding HTTP Routes
```ts
import { httpRouter } from "convex/server";
import { auth } from "./auth.js";

const http = httpRouter();

auth.addHttpRoutes(http);

export default http;
```
```
Tokens:
Raw