workos-convex-debug

Diagnose WorkOS AuthKit integration issues in Convex apps.

9|3|Updated Nov 28, 2025
One-click install
npx skills add https://github.com/get-convex/components-submissions-directory --skill workos-convex-debug-get-convex
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: workos-convex-debug
Source: https://github.com/get-convex/components-submissions-directory/tree/main/.cursor/skills/workos-convex-debug
Command: npx skills add https://github.com/get-convex/components-submissions-directory --skill workos-convex-debug-get-convex

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill helps diagnose and troubleshoot WorkOS AuthKit integration issues within a Convex app, addressing authentication failures, JWT validation errors, and missing or inconsistent identity data.

Core Features & Use Cases

  • Comprehensive diagnostic steps covering environment variables, deployment status of the Convex auth config, WorkOS dashboard JWT templates, and the callback flow to ensure a smooth sign-in experience across development and production.
  • Debug guidance for common scenarios: sign-in button failures, empty or null identity, admin permission checks, and OAuth callback redirects.
  • Practical guidance for validating configuration, logging identity data, and ensuring consistent token verification.

Quick Start

Begin the diagnostic workflow to verify environment variables, confirm auth config deployment, and validate WorkOS JWT claims in Convex.

Frequently Asked Questions about workos-convex-debug

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

FAQPage Schema
How do I fix WorkOS AuthKit authentication failures in my Convex app?

Debug empty or null WorkOS identity in Convex by validating your environment variables, confirming the Convex auth config deployment, and checking WorkOS JWT template claims. Practical guidance includes logging identity data and verifying token configuration to ensure consistent user identity retrieval.

How do I resolve JWT validation errors with WorkOS AuthKit and Convex?

Resolve JWT validation errors with WorkOS AuthKit and Convex by validating your WorkOS dashboard JWT templates and ensuring robust JWT provider setup. The diagnostic workflow checks environment variables and token verification configuration to address authentication failures and missing identity data.

What is the best way to troubleshoot WorkOS admin permission checks in a Convex application?

The best way to troubleshoot WorkOS admin permission checks in a Convex application is to use a code-configuration aware workflow. This validates dashboard configuration, environment variables, and JWT claims to diagnose missing or inconsistent identity data affecting admin permissions.

Can I debug WorkOS AuthKit OAuth callback redirects across development and production environments?

Yes, you can debug WorkOS AuthKit OAuth callback redirects across development and production environments. The diagnostic process validates the callback flow, checks auth config deployment, and verifies environment variables to ensure a smooth sign-in experience in both environments.