Clerk Token Ops

Clerk Token Operations

Overview

This skill gives Claude Code agents a repeatable, zero-surprise playbook for generating Clerk JWTs, exporting them into the Windows PowerShell environment, and validating authentication against the FastAPI backend. It encodes the exact fixes from the November 2025 incidents (missing templates, parser errors, stale tokens) so future runs avoid the same failures.

Activation Signals

Use this skill whenever the task involves:

• Minting or refreshing Clerk JWTs for integration, smoke, or load tests.
• Investigating 401 responses due to expired or malformed tokens.
• Ensuring .env.local and PowerShell sessions stay in sync (CLERK_SECRET_KEY, CLERK_TOKEN).
• Listing or validating Clerk JWT templates (e.g., server-token).
• Teaching another agent how to run scripts/get_clerk_token.py or Set-ClerkToken.ps1 safely.

Guardrails (Do This Before Anything Else)

1. Never copy Markdown links into the terminal. Always use raw paths like scripts/Set-ClerkToken.ps1.
2. Use real Clerk user IDs (e.g., user_35KgiAcvIC0tdtFvJUN1vDkrNYc). Angle brackets or placeholders break PowerShell parsing.
3. Confirm .env.local exists and contains CLERK_SECRET_KEY, CLERK_ISSUER, CLERK_PEM_PUBLIC_KEY, and CLERK_ISSUER_ID.
4. Restart FastAPI after changing .env.local; environment variables load only once per process.
5. Tokens expire in ~60 seconds. Chain generation and testing without delay.

Core Workflow

1. Validate Environment
   • Run Test-Path .env.local and open the file if missing keys.
   • Ensure CLERK_JWT_AUDIENCE stays commented out; session tokens lack aud.
2. Inspect Available JWT Templates
   • powershell -File .\scripts\Set-ClerkToken.ps1 -ListTemplates
   • Confirm server-token exists; if missing, create it in the Clerk dashboard with RS256 signing.
3. Generate & Export Token
   • powershell -File .\scripts\Set-ClerkToken.ps1 -UserId <ACTUAL_USER_ID> -Template server-token [-Persist]
   • Expect: "CLERK_TOKEN exported..." and optional persistence notice.
4. Verify Token Availability
   • echo $env:CLERK_TOKEN
   • Optional: python scripts/get_clerk_token.py --env-file .env.local --user-id ... --template server-token --print-session for debugging.
5. Run Target Tests or API Calls Immediately
   • Example test harness: uv run python main/scripts/test_clerk_auth.py "$env:CLERK_TOKEN" fixtures/test_urs.txt
   • For curl: curl -H "Authorization: Bearer $env:CLERK_TOKEN" http://localhost:8000/jobs -d @payload.json -H "Content-Type: application/json"
6. Audit & Log Verification
   • Tail logs/audit/jobs/audit_*.jsonl to ensure the sub (user ID) and token_iat fields are captured (ALCOA+ compliance).

Quality Checklist

• .env.local contains correct Clerk keys and issuer URLs.
• scripts/get_clerk_token.py runs without HTTP errors and prints JWT.
• scripts/Set-ClerkToken.ps1 outputs success messages (no [System.Char] errors).
• $env:CLERK_TOKEN is non-empty and recent (token_iat within 60 seconds).
• FastAPI endpoint returns 201/200 with token, 401 without token (negative test).
• Audit log entry includes user_id from JWT sub claim.

Troubleshooting Matrix

Example Session (Copy/Paste Ready)

# 1. List templates (sanity check)
powershell -File .\scripts\Set-ClerkToken.ps1 -ListTemplates

# 2. Export fresh token for known test user
powershell -File .\scripts\Set-ClerkToken.ps1 -UserId user_35KgiAcvIC0tdtFvJUN1vDkrNYc -Template server-token -Persist

# 3. Verify environment
$env:CLERK_TOKEN

# 4. Exercise FastAPI endpoint (token expires fast!)
uv run python main/scripts/test_clerk_auth.py "$env:CLERK_TOKEN" fixtures/test_urs.txt

# 5. Tail audit logs for attribution
Get-Content logs/audit/jobs/audit_$(Get-Date -Format yyyyMMdd).jsonl -Tail 3

Extension Hooks

• If tests require Docker Compose: run docker compose -f docker-compose.dev.yml up --build api worker after refreshing tokens.
• CI usage: Wrap helper invocation inside a temporary PowerShell profile so $env:CLERK_TOKEN is available to downstream pytest or uv run commands.
• Documentation updates: When procedures change, sync with main/docs/guides/CLERK_INTEGRATION_TESTING.md and note version in this skill.

References

• scripts/get_clerk_token.py - Python helper hitting Clerk Backend API.
• scripts/Set-ClerkToken.ps1 - PowerShell wrapper for Windows devs.
• main/docs/guides/CLERK_INTEGRATION_TESTING.md - Deep dive guide.
• Anthropic Agent Skills best practices (2025-10-02 spec) for structure and activation cues.

Maintainer: Compliance/Test Enablement Team
Last Updated: 2025-11-16
Status: ✅ Ready for Claude Code agents