Skip to content
Convex Auth Setup

Convex Auth Setup Skill

Convex's official skill for adding passkey or OAuth authentication to a Convex app — including the auth.config.ts wiring and a headless key-generation path that avoids the interactive wizard.

GitHub Docs

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from get-convex/agent-skills.

$ npx skills add get-convex/agent-skills --skill convex-auth

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

  1. Open the skill on GitHub and download the folder that holds its SKILL.md.
  2. Put it at ~/.claude/skills/convex-auth/, where Claude Code picks it up in every project.

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/convex-auth/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/

About

  • Always writes auth.config.ts — the always-signed-out footgun
  • Generates JWT_PRIVATE_KEY and JWKS headlessly with jose, no interactive wizard
  • Sets env vars via the Convex MCP envSet tool or the NAME=VALUE CLI form
  • Passkeys by default; password or OAuth only on explicit request
  • Pre-installs shadcn/ui primitives the generated client code imports
  • Verifies a real sign-in round-trips before finishing

This is a small skill that exists because of two specific failure modes, and it names both of them.

The first is auth.config.ts. Get it wrong or leave it out and a Convex app does not error — it is silently, permanently signed out, with nothing in the logs to explain why. The skill treats writing that file as a mandatory step rather than an optional one, which is the difference between a working sign-in and an afternoon of debugging.

The second is the setup wizard. npx @convex-dev/auth is interactive: it wants a login and a TTY, so it hangs in CI, in anonymous deployments and in any non-interactive agent run. Instead of instructing the agent to run it and hope, the skill generates JWT_PRIVATE_KEY and JWKS deterministically with jose — an extractable RS256 keypair, PKCS8 with newlines flattened to spaces, JWKS shaped as {keys:[{use:"sig", ...publicJwk}]} — and then sets the variables through the Convex MCP envSet tool or the NAME=VALUE CLI form. That last detail matters more than it looks: the private key starts with -----BEGIN, so the space-separated CLI form makes the tool parse the leading dash as an unknown flag.

The rest of the workflow installs @convex-dev/auth at a pinned build and registers it in convex.config.ts (with a note that pnpm will not hoist jose, so it has to be added explicitly), adds the provider in convex/auth.ts — passkeys by default, password or OAuth only on request — wires ConvexAuthProvider, the sign-in component and route guards on the client, and pre-installs any shadcn/ui primitive the generated code imports, because a missing @/components/ui/* is a hard build failure rather than a warning.

It also refuses to declare success on a green build: the last step is verifying that a real sign-in round-trips.

Part of Convex's official agent-skills set. Install with npx skills add get-convex/agent-skills --skill convex-auth.

Try it

Once installed, ask your agent something like:

Add passkey sign-in to this Convex app and wire the route guards — do it headlessly, I'm running in CI.

SKILL.md

The instructions your agent loads, as published by Convex.

SKILL.md
name
convex-auth
description
Add authentication (passkeys/OAuth) to the current Convex app, including the auth.config.ts wiring.

<!-- GENERATED from convex-agents content/capabilities/auth.json — do not edit by hand. -->

Add sign-in to the app

Install and wire @convex-dev/auth for the current app: a provider (passkeys by default, or OAuth/password), the server config, the client hooks, and a sign-in UI — correctly, including the auth.config.ts that's the #1 real-world auth footgun.

Workflow
  1. Install @convex-dev/auth (pinned build) and add it to convex.config.ts. With pnpm, also pnpm add jose (it won't hoist otherwise); you need it for step 3.
  2. Add the provider in convex/auth.ts (Passkey by default; Password or OAuth like Google on request).
  3. Generate the auth keys HEADLESSLY. Do NOT run the interactive npx @convex-dev/auth wizard: it needs a login/TTY and hangs in non-interactive, anonymous, or CI runs (the #1 auth time-sink). Generate JWT_PRIVATE_KEY + JWKS deterministically with jose:

node -e 'import("jose").then(async({generateKeyPair,exportPKCS8,exportJWK})=>{const k=await generateKeyPair("RS256",{extractable:true});const priv=await exportPKCS8(k.privateKey);const pub=await exportJWK(k.publicKey);process.stdout.write(JSON.stringify({JWT_PRIVATE_KEY:priv.trimEnd().replace(/\n/g," "),JWKS:JSON.stringify({keys:[{use:"sig",...pub}]})}))})' > .auth-keys.json
Then set JWT_PRIVATE_KEY and JWKS (from .auth-keys.json) plus SITE_URL on the deployment. Prefer the Convex MCP envSet tool, one call per var, to avoid shell-quoting the multi-line key. CLI fallback: use the NAME=VALUE form (npx convex env set "JWT_PRIVATE_KEY=$JWT"), NEVER env set JWT_PRIVATE_KEY "$JWT" (the value starts with -----BEGIN and the CLI parses the leading - as an unknown flag). SITE_URL is the dev URL (e.g. http://localhost:3000). Delete .auth-keys.json after.

  1. Write convex/auth.config.ts (the silently-always-signed-out bug lives here if it's wrong).
  2. Wire the client: ConvexAuthProvider, the sign-in component, and route guards. If you import shadcn/ui primitives (button, input, textarea, label, and so on), add them first with npx shadcn@latest add <name>; a missing @/components/ui/* is a hard build error.
  3. Verify a sign-in round-trips before declaring done.
Rules
  • Generate JWT_PRIVATE_KEY/JWKS with jose (extractable RS256; PKCS8 newlines to spaces; JWKS = {keys:[{use:"sig", ...publicJwk}]}). Do NOT run the interactive npx @convex-dev/auth wizard: it hangs headless/anonymous. Set the vars via the MCP envSet tool or the NAME=VALUE CLI form.
  • Always write auth.config.ts: a missing/incorrect one makes the app silently always-signed-out with no error.
  • Passkeys by default; only switch to password/OAuth on explicit request.
  • Install any shadcn/ui primitive you import up front (npx shadcn@latest add ...); a missing @/components/ui/* is a hard build failure.
  • Verify a real sign-in works before finishing.
Install

Skill: Convex

by Convex

Featured

Convex's official top-level agent skill — routes an agent to the right convex-* skill for the task and to a served capability catalogue that stays current without a reinstall.

New

Convex's official skill for turning a one-sentence app idea into a running Next.js + Convex template with an anonymous dev deployment, plus strict rules for writing Convex functions that compile and push first time.

Convex's official skill for changing the schema of a deployed app without breaking it — add the field optional, backfill with @convex-dev/migrations, verify, then tighten the validator.

Browse all skills →