Features

• Every auth method — Password, Google/GitHub/Apple/Microsoft OAuth, magic links, passkeys, TOTP, anonymous, phone, device flow (RFC 8628)
• Group SSO — OIDC, SAML 2.0, SCIM 2.0 via the auth.connection.* admin facade
• API keys — Scoped permissions, per-key rate limiting, rotation, SHA-256 hashing
• Groups and memberships — Hierarchical groups, permissions, grants, roles, invites, cascade operations
• SSR — Cookie-based auth for SvelteKit, TanStack Start, Next.js
• Multi-access — auth.ctx(), auth.context(ctx), and auth.request.context(ctx, request) cover app, imperative, and raw HTTP auth
• Convex component — Isolated tables, typed helpers, zero-config defaults

vNext preview

The vNext docs use the new Convex-native setup vocabulary: defineAuth, definePermissions, permissions, grants, object args, native Convex pagination, typed app env via authEnv, and a flat group connection (SSO) admin facade auth.connection.*. See packages/auth/MIGRATION-vNext.md for the target shape and migration notes.

API design

@robelest/convex-auth is a Convex component, but unlike single-purpose components — which you instantiate as a class (new RateLimiter(components.rateLimiter), new Resend(components.resend)) — it spans many domains: users, sessions, accounts, group memberships, SSO connections, OAuth clients, and API keys. Rather than one class with dozens of methods, it uses a definition-first factory that returns a facade namespaced by domain:

import { defineAuth } from "@robelest/convex-auth/server";
import { definePermissions } from "@robelest/convex-auth/permissions";
import { password, google } from "@robelest/convex-auth/providers";
import { components } from "./_generated/api";

export const permissions = definePermissions({
  grants: ["members.read", "sso.connection.manage"],
  roles: { admin: { label: "Admin", grants: ["members.read"] } },
});

export const auth = defineAuth(components.auth, {
  providers: [password(), google()],
  permissions,
});

// Every method is (ctx, objectArgs), grouped by domain:
await auth.user.get(ctx, { id });
await auth.member.assert(ctx, { userId, groupId, roleIds: ["admin"] });
await auth.connection.create(ctx, { groupId, protocol: "oidc" });

Configuration is passed once to defineAuth; related operations live under auth.user.*, auth.session.*, auth.account.*, auth.member.*, auth.invite.*, auth.connection.*, auth.oauth.*, auth.key.*, and auth.request.*. All methods take Convex-native object args ({ id }, { ids }, { userId }, { where }, { paginationOpts }, { data }, { patch }) and return Convex-native shapes (Doc | null, PaginationResult). defineAuth is the single canonical setup entry point — see packages/auth/LEXICON.md for the full naming and shape contract.

Package exports

Import path	Use
@robelest/convex-auth/server	Backend: defineAuth, the auth.* facade, authEnv, authEvents, and HTTP route helpers
@robelest/convex-auth/convex.config	The component definition for app.use(auth) in convex.config.ts
@robelest/convex-auth/permissions	definePermissions and the grant/role types
@robelest/convex-auth/providers (+ /providers/*)	Auth providers: password, google, github, apple, microsoft, passkey, totp, anonymous, email, device, …
@robelest/convex-auth/client	Framework-agnostic browser client factory (client() — sign-in/out, token store)
@robelest/convex-auth/react	React bindings: ConvexAuthProvider, useAuth, useConvexAuthClient
@robelest/convex-auth/expo	React Native / Expo client
@robelest/convex-auth/browser	Low-level browser primitives (navigation, passkey, web locks)
@robelest/convex-auth/core	createAuthContext and low-level building blocks for custom integrations

Documentation

convex-auth.pages.dev

Section	Description
Getting Started	Installation, providers, environment variables
API Reference	auth.user, auth.session, auth.group, auth.key, and more
Group SSO	OIDC, SAML, SCIM, audit, webhooks
SSR Integration	SvelteKit, TanStack Start, Next.js
Guides	Multi-access, device flow, authorization, production
Reference	Config options, error codes, CLI, architecture

Contributing

pnpm install
vp run check
vp test --run --project convex

Directory	Description
packages/auth	Auth component, server helpers, providers, CLI
tests/	Vitest test suite (convex + node projects)
docs/	Starlight documentation site

License

Apache-2.0