auth-setup

Set up OAuth or JWT authentication and map provider identities to Convex users.

Updated Mar 7, 2026
One-click install
npx skills add https://github.com/jcdiv47/cool-paper --skill auth-setup-jcdiv47
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: auth-setup
Source: https://github.com/jcdiv47/cool-paper/tree/main/.agents/skills/convex-auth-setup
Command: npx skills add https://github.com/jcdiv47/cool-paper --skill auth-setup-jcdiv47

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Provide a clear, repeatable pattern for authenticating users in Convex applications and mapping external provider identities to application users so that authentication, authorization, and user management are consistent and secure.

Core Features & Use Cases

  • User provisioning and identity mapping: guidance for creating a users table with a tokenIdentifier index and upserting users on first sign-in.
  • Auth helper functions: patterns for getCurrentUser, getCurrentUserOrNull, and requireAdmin to centralize authentication checks and error handling.
  • Access control patterns: examples for owner-only operations, resource ownership checks, team-based membership gates, public vs private queries, and client integration with providers like WorkOS or Auth0.
  • Client and environment setup: directions for wiring Convex client auth to a provider token, required environment variables, and calling storeUser on sign-in.

Quick Start

Set up a users table with a tokenIdentifier index, implement getCurrentUser and storeUser helpers in your Convex backend, and configure your client to supply provider tokens (for example WorkOS or Auth0) and call storeUser after sign-in.

Frequently Asked Questions about auth-setup

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I set up authentication in Convex with OAuth providers?

To set up Convex authentication, create a users table with a tokenIdentifier index, implement storeUser and getCurrentUser helpers, and configure your client to pass provider tokens from services like WorkOS or Auth0 to map external identities to application users.

How does identity mapping work for user provisioning in Convex?

Identity mapping in Convex links external provider identities to application users by upserting user records upon first sign-in using a tokenIdentifier index, ensuring consistent authentication and authorization across sessions.

Can I use WorkOS or Auth0 for role-based access control in Convex?

Yes, you can use WorkOS or Auth0 for role-based access control in Convex by wiring client auth to provider tokens and implementing helper functions like requireAdmin to centralize authorization checks and team membership gates.

What's the best way to implement owner-only operations and team membership checks in Convex?

The best way to implement access control in Convex is by using auth helper functions like getCurrentUser to verify resource ownership and validate team-based membership gates before allowing owner-only operations or private queries.

Do I need a specific database schema for secure user authentication in Convex?

Yes, secure user authentication in Convex requires a users table configured with a tokenIdentifier index to properly map external JWT provider identities and support upserting users on first sign-in.

Why does my Convex auth return null when querying the current user?

Convex auth may return null if the client is not properly configured to supply provider tokens or if the storeUser function is not called after sign-in to map the external identity to the application users table.