convex-auth

Original：🇺🇸 English

Translated

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

1installs

Sourceigorwarzocha/opencode-workflows

Added on2026-02-10

NPX Install

npx skill4agent add igorwarzocha/opencode-workflows convex-auth

SKILL.md Content

View Translation Comparison →

<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>