Configuration

`createAuth(component, config)`

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

const auth = createAuth(components.auth, {
  providers: [
    /* ... */
  ],
  // All options below are optional
  session: {
    totalDurationMs: 30 * 24 * 60 * 60 * 1000, // 30 days
    inactiveDurationMs: 7 * 24 * 60 * 60 * 1000, // 7 days
  },
  jwt: {
    durationMs: 60 * 1000, // 1 minute
  },
  signIn: {
    max_failed_attempts_per_hour: 10,
  },
  callbacks: {
    afterUserCreatedOrUpdated: async (ctx, { userId, existingUser }) => {
      /* ... */
    },
  },
  authorization: {
    roles: {
      member: {
        label: "Member",
        grants: [],
      },
    },
  },
});

Config options

Option	Type	Default	Description
`providers`	`AuthProviderConfig[]`	required	Auth methods to enable
`session.totalDurationMs`	`number`	30 days	Maximum session lifetime
`session.inactiveDurationMs`	`number`	varies	Inactive session timeout
`jwt.durationMs`	`number`	60s	JWT token lifetime
`signIn.max_failed_attempts_per_hour`	`number`	10	Rate limit for failed sign-in attempts
`callbacks.afterUserCreatedOrUpdated`	`function`	—	Post-sign-in hook
`authorization.roles`	`Record<string, Role>`	`{}`	App-defined role definitions and grants

Note: Email transport is configured via new Email({ from, send }) in the providers array, not as a top-level config option.

See Authorization Patterns for the recommended authorization model.

Return value

createAuth returns an object with:

signIn — Action for client sign-in
signOut — Action for client sign-out
store — Mutation for session token exchange
auth.user.* — User helpers
auth.session.* — Session helpers
auth.account.* — Account helpers
auth.group.* — Group helpers
auth.member.* — Membership helpers
auth.invite.* — Invite helpers
auth.key.* — API key helpers
auth.http.* — HTTP route helpers
auth.group.sso.* — inbound group SSO helpers (only when new SSO() is in providers)
auth.group.sso.scim.* — SCIM provisioning helpers (only when new SSO() is in providers)
InferClientApi<typeof auth> — Type-level utility; use as the generic for client() on the frontend to get conditional passkey/totp/device helpers

API layers

Auth-flow actions

signIn, signOut, and store are the app-facing Convex functions used by the frontend auth client.

Helper namespaces

auth.*, auth.group.sso.*, and auth.group.sso.scim.* are server-side helper APIs for your Convex code.

Mounted group SSO RPC

api.auth.group.* only exists after your app mounts or writes public group SSO wrappers.

The auth.group.sso.* and auth.group.sso.scim.* namespaces are server-side helper APIs. They are not automatically exposed as client-callable Convex functions just because they exist on the returned object.

If your app wants public group SSO admin RPC, mount it explicitly in your app:

write your own Convex wrappers in a file such as convex/auth/group.ts.

See the Group SSO RPC guide for the recommended flat group SSO RPC shape.