Agent skill

convex-auth

Core authentication patterns for Convex backends. Use when implementing auth checks in functions, storing users in database, creating auth helpers, or debugging auth issues. Works with any auth provider (Clerk, WorkOS, Auth0, etc.).

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/convex-auth-skill

SKILL.md

Convex Authentication - Core Patterns

This skill covers universal auth patterns that work with ANY authentication provider.

Auth in Functions

Access the authenticated user via ctx.auth.getUserIdentity():

typescript
import { query, mutation, action } from './_generated/server';

export const myQuery = query({
  args: {},
  handler: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    if (identity === null) {
      throw new Error('Not authenticated');
    }
    // identity.tokenIdentifier - unique across providers
    // identity.subject - user ID from provider
    // identity.email, identity.name, etc. (if configured)
  }
});

UserIdentity Fields

Field Guaranteed Description
tokenIdentifier ✅ Unique ID (subject + issuer combined)
subject ✅ User ID from auth provider
issuer ✅ Auth provider domain
email Provider-dependent User's email
name Provider-dependent Display name
pictureUrl Provider-dependent Avatar URL

Critical: Race Condition Prevention

Problem: Queries can execute before auth is validated on page load.

Client-side: Always use useConvexAuth() from convex/react, NOT your provider's hook:

typescript
// ✅ Correct - waits for Convex to validate token
import { useConvexAuth } from 'convex/react';
const { isLoading, isAuthenticated } = useConvexAuth();

// ❌ Wrong - only checks provider, not Convex validation
const { isSignedIn } = useAuth(); // from @clerk/clerk-react

Skip queries until authenticated:

typescript
const user = useQuery(api.users.current, isAuthenticated ? {} : 'skip');

Use Convex auth components:

typescript
import { Authenticated, Unauthenticated, AuthLoading } from "convex/react";

<Authenticated>
  <Content /> {/* Queries here are safe */}
</Authenticated>
<Unauthenticated>
  <SignInButton />
</Unauthenticated>

Storing Users in Database

See USERS.md for complete patterns including:

  • Schema design with indexes
  • Storing users via client mutation
  • Storing users via webhooks (recommended for production)
  • Helper functions for user lookup

Custom Auth Wrappers

Create authenticated function wrappers using convex-helpers:

typescript
// convex/lib/auth.ts
import {
  query,
  mutation,
  action,
  QueryCtx,
  MutationCtx,
  ActionCtx
} from './_generated/server';
import {
  customQuery,
  customMutation,
  customAction,
  customCtx
} from 'convex-helpers/server/customFunctions';
import { ConvexError } from 'convex/values';

async function requireAuth(ctx: QueryCtx | MutationCtx | ActionCtx) {
  const identity = await ctx.auth.getUserIdentity();
  if (!identity) {
    throw new ConvexError('Not authenticated');
  }
  return identity;
}

export const authQuery = customQuery(
  query,
  customCtx(async (ctx) => {
    const identity = await requireAuth(ctx);
    return { identity };
  })
);

export const authMutation = customMutation(
  mutation,
  customCtx(async (ctx) => {
    const identity = await requireAuth(ctx);
    return { identity };
  })
);

export const authAction = customAction(
  action,
  customCtx(async (ctx) => {
    const identity = await requireAuth(ctx);
    return { identity };
  })
);

Usage:

typescript
import { authQuery } from './lib/auth';

export const myProtectedQuery = authQuery({
  args: {},
  handler: async (ctx) => {
    // ctx.identity is guaranteed to exist
    const userId = ctx.identity.subject;
  }
});

HTTP Actions with Auth

Pass JWT in Authorization header:

typescript
// Client
fetch('https://your-deployment.convex.site/api/endpoint', {
  headers: { Authorization: `Bearer ${jwtToken}` }
});

// convex/http.ts
import { httpAction } from './_generated/server';

export const myEndpoint = httpAction(async (ctx, request) => {
  const identity = await ctx.auth.getUserIdentity();
  if (!identity) {
    return new Response('Unauthorized', { status: 401 });
  }
  // ...
});

Debugging Checklist

See DEBUG.md for detailed troubleshooting steps.

Quick checks:

  1. ctx.auth.getUserIdentity() returns null?
    • Check if query runs before auth completes (use "skip" pattern)
    • Check auth.config.ts is deployed (npx convex dev)
  2. Check Settings > Authentication in Convex Dashboard
  3. Verify JWT token at https://jwt.io - check iss and aud fields
  4. Ensure domain in auth.config.ts matches JWT iss
  5. Ensure applicationID matches JWT aud

DO ✅

  • Always check ctx.auth.getUserIdentity() in public functions
  • Use useConvexAuth() hook, not provider's auth hook
  • Skip queries with "skip" until authenticated
  • Use <Authenticated> component to gate protected content
  • Store users in DB for cross-user queries
  • Use tokenIdentifier or subject as unique user key

DON'T ❌

  • Trust client-side auth alone (Convex is a public API)
  • Run queries before checking isAuthenticated
  • Use .filter() to find users by token (use index)
  • Assume identity fields exist (check provider config)
  • Forget to redeploy after changing auth.config.ts

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results