# Set Up Convex Authentication

Convex auth setup can fail when provider wiring, environment variables, and backend checks do not match. This skill guides the correct provider flow and adds verified Convex authentication patterns.

## Install

```bash
npx skillstore add get-convex/convex-setup-auth
```

## Metadata

- Status: approved
- Slug: get-convex-convex-setup-auth
- Skillstore revision: r1
- Version status: missing
- Tree hash: 1d9baf97c5c5393442d205e6af4a3f14e9817ec8ee412ec540051d020a21794b
- Author: get-convex
- GitHub username: get-convex
- License: MIT
- Repository: https://github.com/get-convex/agent-skills/tree/main/skills/convex-setup-auth/
- Ref: 30c73eac2afe762f6aa9c4553158769369d47351
- Supported tools: Claude, Codex, Claude Code
- Audit status: complete
- Agent install advisory: allowed
- Manual install advisory: allowed
- Artifact signature: available
- Audit attestation: unavailable
- Human verification: not\_verified
- Risk factors: network, env\_access, external\_commands
- Quality score: 80
- Quality tier: silver
- Public page: https://skillstore.pages.dev/skills/get-convex-convex-setup-auth
- Manifest: https://skillstore.pages.dev/api/skills/get-convex-convex-setup-auth/manifest

## Capabilities

- Helps choose between Convex Auth, Clerk, WorkOS AuthKit, Auth0, and custom JWT providers.
- Guides setup of convex/auth.config.ts and provider-specific client wrappers.
- Explains required environment variables for local and production authentication setup.
- Shows how to protect Convex queries and mutations with ctx.auth.getUserIdentity\(\).
- Covers optional user table mapping and role-based access control when the app needs it.
- Provides validation checklists for sign-in, Convex auth state, and protected backend functions.

## Use Cases

- Launch login in a Convex app: A product engineer adds sign-up, sign-in, and backend identity checks to a new Convex project.
- Connect an existing auth provider: A full-stack developer links Clerk, WorkOS AuthKit, or Auth0 to Convex without replacing current auth flows.
- Prepare production auth configuration: A technical lead reviews local and production provider settings before deploying protected Convex features.

## Prompt Templates

### Add basic login

```
Add authentication to this Convex app. Ask me which provider to use if the repo does not make it clear.
```

### Wire an existing provider

```
This app already uses Clerk. Connect it to Convex auth, preserve the current sign-in flow, and verify Convex sees authenticated users.
```

### Protect backend functions

```
Review my Convex queries and mutations. Add server-side identity checks and authorization for user-owned records where needed.
```

### Prepare production auth

```
Configure production-ready Convex authentication for WorkOS AuthKit. Separate dev and production settings, then provide a validation checklist.
```

## Limitations

- Requires user confirmation when provider accounts, dashboard actions, or CLI logins are interactive.
- Does not replace current provider documentation; it directs the agent to verify official docs.
- Cannot validate production tenants unless required credentials and deployment access are available.
- May need manual checks when browser automation is unavailable.

## Best Practices

- Choose the auth provider before writing setup code.
- Use official provider documentation for current package and CLI steps.
- Verify both frontend login and ctx.auth.getUserIdentity\(\) in Convex functions.

## Anti Patterns

- Do not trust client-provided user IDs for protected data.
- Do not add a users table unless the app needs app-level user records.
- Do not claim setup is complete until Convex recognizes the authenticated session.

## Security Audit

- Audited at: 2026-07-05T15:07:11.443\+00:00
- Summary: AI review found the static detections are false positives from Markdown links, inline code, TypeScript examples, and documented environment variable names. The skill handles sensitive auth configuration, but the reviewed files do not show credential exfiltration, prompt injection, unauthorized network requests, or executable shell behavior.

## Stats

- Views: 140
- Downloads: 7
- Favorites: 0
- Popularity score: 0