Skip to content
Convex Auth Setup

Convex Auth SetupSkill

by Convex
Added to Onei
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: Convex

by Convex

New

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.

Development

Skill: Shopify Liquid & Themes

by Shopify

New

Official Shopify skill for theme development in Liquid — teaches an agent the modern theme architecture of sections, blocks and snippets, and validates generated templates and schemas.

Development
1 views

Skill: Shopify Admin GraphQL

by Shopify

New

Shopify's official skill for writing Admin GraphQL queries and mutations — it searches the live API docs and validates every operation against the schema before handing you code.

Development
1 views

Skill: Twilio AI Agent Architect

by Twilio

New

Planning skill that interrogates your use case before any code is written, then recommends the right Twilio Conversations stack — ConversationRelay, Memory, Intelligence, Orchestrator, TaskRouter — and the implementation skills to follow.

Development
1 views
Browse all skills →