Skip to content
Convex Auth Setup

Convex Auth SetupSkill

by Convex
Added to Onei
11 views
Repository Docs
markdown Development

Summary

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.

Features

  • 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

Install This Skill

Add this skill to your favorite AI agent in a few steps.

Any AI agent

This skill is plain instructions — it works with any assistant that accepts custom instructions or system prompts.

  1. Copy the skill content with the button below.
  2. Paste it into your agent's instruction file or system prompt (for example AGENTS.md, .cursorrules, or a custom instructions field).
  3. Ask the agent to apply the skill whenever the task matches.

Skill Content

Markdown Content

Copy this content and use it with your preferred AI agent

---
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.
4. Write convex/auth.config.ts (the silently-always-signed-out bug lives here if it's wrong).
5. 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.
6. 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.

Usage Instructions

Learn how to use this skill with different AI agents.

Claude Desktop

In Claude Code: /convex-auth. Install the parent convex skill alongside it so the agent can route to related capabilities.

Example Usage

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

Description

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.

Related Skills

Skill: NVIDIA Warp Gradient Debugging

by NVIDIA

New

Diagnoses wrong gradients in differentiable NVIDIA Warp programs by measuring first — comparing autodiff against finite differences on a shrunk reproduction before proposing any fix.

Development
3 views

Skill: Google Workspace CLI (gws)

by Google Workspace

New

Google's official skill for the gws CLI — drive Gmail, Drive, Calendar, Sheets, Docs, Chat and Admin APIs from an agent, with Model Armor screening.

Development
4 views 1 copies

Skill: Netlify Database

by Netlify

New

Netlify's official skill for zero-config managed Postgres — querying from Functions, Drizzle setup, migrations and per-preview database branches.

Development
3 views

Skill: WordPress Block Development

by WordPress

New

Official WordPress skill for Gutenberg block work: block.json, attributes and serialization, dynamic rendering, and the deprecation path that keeps existing content valid.

Development
3 views 1 copies
Browse all skills →