Installation

Install

Quick Setup (CLI)

The setup flow is:

  1. install @robelest/convex-auth
  2. start a Convex deployment with convex dev
  3. run the auth setup wizard

The wizard handles everything:

  • key generation
  • convex.config.ts
  • auth.ts — provider config + sign-in actions
  • auth/core.ts — lightweight context for queries and mutations
  • auth.config.ts — native Convex JWT trust config
  • http.ts

API layers

Client auth flow

Frontends use client({ convex, api: api.auth }). The public client contract is signIn + signOut; store is internal runtime plumbing.

Server helpers

`auth.user.*`, `auth.group.sso.*`, and `auth.group.sso.scim.*` are server-side helpers for Convex code. They are not automatically public RPC.

Optional group SSO RPC

If your app wants client-callable group SSO admin APIs, expose app-owned wrappers such as convex/auth/group.ts.

1. Register the component

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

const app = defineApp();
app.use(auth);
export default app;

2. Configure providers

// convex/auth.ts
import { createAuth } from "@robelest/convex-auth/component";
import { components } from "./_generated/api";
import { github } from "@robelest/convex-auth/providers/github";

const auth = createAuth(components.auth, {
  providers: [
    github({
      clientId: process.env.AUTH_GITHUB_ID!,
      clientSecret: process.env.AUTH_GITHUB_SECRET!,
    }),
  ],
});

export { auth };
export const { signIn, signOut, store } = auth;

store and http stay exported so the auth runtime can cross the Convex component boundary without storing env-backed provider secrets in component tables. Frontend apps should pass only api.auth into the client SDK.

3. Create the auth context

// convex/auth/core.ts
import { createAuthContext } from "@robelest/convex-auth/core";
import { components } from "../_generated/api";

export const auth = createAuthContext(components.auth);

Queries and mutations import auth from ./auth/core — this keeps provider and crypto code out of your query bundles entirely.

4. Trust the Convex Auth JWT issuer

// convex/auth.config.ts
export default {
  providers: [
    {
      domain: `${process.env.CONVEX_SITE_URL}/auth`,
      applicationID: "convex",
    },
  ],
};

CONVEX_SITE_URL is provided automatically by Convex. This file is what makes ctx.auth.getUserIdentity() work against tokens issued by Convex Auth.

5. Auth HTTP routes

Mount the app-side auth protocol alias from convex/http.ts. This keeps OAuth secrets in deployment env vars while the component still owns auth storage and state.

// convex/http.ts
import { auth } from "./auth";

export default auth.http();