auth-setup

Maps identity providers to a Convex users schema and enforces authorization rules.

Updated Jun 8, 2024
One-click install
npx skills add https://github.com/shadeiskndr/portfolio --skill auth-setup-shadeiskndr
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: auth-setup
Source: https://github.com/shadeiskndr/portfolio/tree/main/.agents/skills/auth-setup
Command: npx skills add https://github.com/shadeiskndr/portfolio --skill auth-setup-shadeiskndr

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps you set up secure authentication in Convex by managing users, mapping identity from your auth provider, and enforcing authorization consistently across your backend.

Core Features & Use Cases

  • User identity mapping: Stores provider identity (tokenIdentifier) into a Convex users table with indexes for fast lookup by token and email.
  • Reusable auth helpers: Provides functions like getCurrentUser and getCurrentUserOrNull to centralize auth retrieval and reduce duplicated checks.
  • Role-based authorization: Implements patterns such as requireAdmin and owner-only access for protected mutations.
  • Protected vs public queries: Supports hybrid access patterns where authenticated users see more data (e.g., drafts) while anonymous users only see public records.
  • First sign-in upsert: Adds a storeUser mutation to create users on first sign-in and patch/update fields on subsequent logins.
  • Client authentication integration: Demonstrates WorkOS AuthKit integration for both React/Vite and Next.js, including token wiring into Convex.

Quick Start

Tell the AI: "Set up Convex authentication with a users schema, add getCurrentUser/getCurrentUserOrNull helpers, implement storeUser for first sign-in, and enforce role + ownership checks for protected mutations in my Convex app."

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 role-based access control in Convex?

Role-based access control in Convex is set up by creating protected mutations that validate authentication using helper functions like requireAdmin. This enforces authorization rules consistently across your backend before any data changes occur.

How do I map external identity providers to a Convex users schema?

You map external identity providers by storing the provider's tokenIdentifier into a Convex users table. Using indexes for fast lookup by token and email, a storeUser mutation upserts the user data on first sign-in and patches fields on subsequent logins.

Does Convex authentication work with WorkOS for React and Next.js?

Yes, Convex authentication works with WorkOS AuthKit for both React/Vite and Next.js. The integration involves wiring the client tokens from WorkOS directly into your Convex client configuration to secure your application.

What is the best way to handle hybrid public and private queries in Convex?

The best way to handle hybrid queries in Convex is to check authentication status within your query functions. This allows authenticated users to see more data like drafts while anonymous users only see public records.

How do I enforce owner-only access for resource mutations in Convex?

You enforce owner-only access by implementing protected mutations that validate the current user's identity against the resource owner. Helper functions like getCurrentUser centralize retrieval of ctx.auth.getUserIdentity to prevent unauthorized modifications.