How do I install the Convex Auth skill?

Run npx skillmds@latest add igorwarzocha/convex-auth in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Convex Auth safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: makes network calls, reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Convex Auth?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Convex Auth free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Convex Auth?

igorwarzocha (@igorwarzocha) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Convex Auth by igorwarzocha — Agent Skill

Name: Convex Auth
Rating: 4.2 (5 reviews)
Author: igorwarzocha

Convex Auth

Implement Convex authentication and authorization patterns with OIDC providers or Convex Auth. Use for auth provider setup, ctx.auth usage, user identity handling, and auth-aware schema patterns. Use proactively when users mention auth, JWT, Clerk/Auth0/WorkOS, or Convex Auth. Examples: - user: "Add auth to Convex" → choose provider and outline setup - user: "Get current user" → use ctx.auth.getUserIdentity and checks - user: "Service-to-service access" → use shared secret pattern

File contents

Auth Operations

In functions: ctx.auth.getUserIdentity() returns tokenIdentifier, subject, issuer plus provider claims.
Custom JWT auth MAY expose claims at identity["properties.email"] style paths.
User storage patterns:
- Client mutation to store user from JWT, or webhook from provider to upsert users.
- Index lookups SHOULD use by_token / byExternalId.
Webhooks: You MUST implement via HTTP actions and verify signatures with provider SDK; signing secrets MUST be stored in env vars.

Convex Auth (Beta) Specifics

Supported Methods:
1. Magic Links & OTPs: Email-based links or codes.
2. OAuth: GitHub, Google, Apple, etc.
3. Passwords: Supports reset flows and optional email verification.
Components: Does not provide UI components; You MUST build them in React using library hooks.
Next.js: SSR/Middleware support is experimental/beta.

Server Function Patterns

You MUST read identity via ctx.auth.getUserIdentity().
You MUST enforce row-level authorization in every public function.
You SHOULD NOT expose sensitive logic via public functions; prefer internal ones.

Service-to-service Access

If no user JWT is available, You SHOULD use a shared secret pattern.
You MUST store secrets in deployment env vars; MUST NOT hardcode.

Client Guidance

You MUST follow provider quickstarts; MUST NOT invent flows.
You SHOULD NOT rely on auth data in client-only code without server verification.

---name: convex-authdescription: Implement Convex authentication and authorization patterns with OIDC providers or Convex Auth. Use for auth provider setup, ctx.auth usage, user identity handling, and auth-aware schema patterns. Use proactively when users mention auth, JWT, Clerk/Auth0/WorkOS, or Convex Auth. Examples: - user: "Add auth to Convex" → choose provider and outline setup - user: "Get current user" → use ctx.auth.getUserIdentity and checks - user: "Service-to-service access" → use shared secret pattern--- <overview> Implement Convex authentication and authorization patterns with OIDC providers (Clerk, Auth0, WorkOS) or the built-in Convex Auth library. </overview> <reference> - **Auth overview**: https://docs.convex.dev/auth - **Convex Auth (beta)**: https://docs.convex.dev/auth/convex-auth - **Auth methods**: https://labs.convex.dev/auth - **Clerk Integration**: https://docs.convex.dev/auth/clerk - **WorkOS Integration**: https://docs.convex.dev/auth/authkit/ </reference> <context name="Auth Concepts"> - Convex uses OpenID Connect JWTs. - Integrations: Clerk, WorkOS AuthKit, Auth0; custom OIDC supported. - Convex Auth (Beta): A built-in library (labs.convex.dev) supporting Magic Links, OTPs, OAuth, and Passwords without external services. - Identity: Accessed via `ctx.auth.getUserIdentity()` in server functions. - Authorization: Enforced per public function; sensitive logic MUST use internal functions. </context> <rules> ### Auth Operations - In functions: `ctx.auth.getUserIdentity()` returns `tokenIdentifier`, `subject`, `issuer` plus provider claims. - Custom JWT auth MAY expose claims at `identity["properties.email"]` style paths. - User storage patterns: - Client mutation to store user from JWT, or webhook from provider to upsert users. - Index lookups SHOULD use `by_token` / `byExternalId`. - Webhooks: You MUST implement via HTTP actions and verify signatures with provider SDK; signing secrets MUST be stored in env vars. ### Convex Auth (Beta) Specifics - Supported Methods: 1. **Magic Links & OTPs**: Email-based links or codes. 2. **OAuth**: GitHub, Google, Apple, etc. 3. **Passwords**: Supports reset flows and optional email verification. - Components: Does not provide UI components; You MUST build them in React using library hooks. - Next.js: SSR/Middleware support is experimental/beta. ### Server Function Patterns - You MUST read identity via `ctx.auth.getUserIdentity()`. - You MUST enforce row-level authorization in every public function. - You SHOULD NOT expose sensitive logic via public functions; prefer internal ones. ### Service-to-service Access - If no user JWT is available, You SHOULD use a shared secret pattern. - You MUST store secrets in deployment env vars; MUST NOT hardcode. ### Client Guidance - You MUST follow provider quickstarts; MUST NOT invent flows. - You SHOULD NOT rely on auth data in client-only code without server verification. </rules>

Frequently asked questions