Skip to main content

Getting started

For AI agents: see llms.txt for the complete documentation index. Markdown versions are available by adding .md to a page URL or requesting Accept: text/markdown.

Every project using Convex Auth starts with these steps.

  1. Install Convex Auth

    Add the Convex Auth package to your project.

    npm i @convex-dev/auth
  2. Install the core component

    Register the Convex Auth component in convex/convex.config.ts. The guide of each sign-in method adds more components to this file.

    convex/convex.config.ts
    import { defineApp } from "convex/server";
    import auth from "@convex-dev/auth/convex.config.js";

    const app = defineApp();

    app.use(auth);

    export default app;
  3. Configure the authentication provider

    Create convex/auth.config.ts. This file tells your deployment to accept the access tokens of Convex Auth. Your deployment signs the access tokens with its own key, thus you do not have secrets to configure.

    convex/auth.config.ts
    import type { AuthConfig } from "convex/server";
    import { convexAuthProvider } from "@convex-dev/auth/server";

    export default {
      providers: [convexAuthProvider()],
    } satisfies AuthConfig;
  4. Set up Convex Auth

    Create convex/auth.ts, and export the functions of the core from it. The guide of each sign-in method adds its functions to this file.

    convex/auth.ts
    import { components } from "./_generated/api";
    import { setupConvexAuth } from "@convex-dev/auth/server";

    const auth = setupConvexAuth({ component: components.auth });
    export const { signOut, refreshSession, isAuthenticated } = auth;

Install a sign-in method​

Pick a sign-in method and follow its guide to wire it up: