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
  • http.ts

API layers

Client auth flow

signIn, signOut, and store are the only required client-callable auth functions. Frontends use them through client({ convex, api: api.auth }).

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 auth

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

const auth = createAuth(components.auth, {
  providers: [
    OAuth(
      new GitHub(process.env.AUTH_GITHUB_ID!, process.env.AUTH_GITHUB_SECRET!),
    ),
  ],
});

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

3. Wire up HTTP routes

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

const http = httpRouter();
auth.http.add(http);
export default http;

auth.http.add registers OAuth callbacks and JWKS endpoints in one call.