Skip to content

cloudthinker-ai/CloudSkills / skills/connections/managing-clerk

managing-clerk

Verified

Use when working with Clerk — clerk authentication and user management platform covering users, sessions, organizations, invitations, and sign-in methods. Use when analyzing user growth, monitoring authentication health, reviewing organization membership, managing Clerk users, or auditing sign-in patterns.

Clerk Management Skill

Manage and analyze Clerk authentication resources including users, organizations, and sessions.

API Conventions

Authentication

All API calls use Bearer secret key, injected automatically.

Base URL

https://api.clerk.com/v1

Core Helper Function

#!/bin/bash

clerk_api() {
    local method="$1"
    local endpoint="$2"
    local data="${3:-}"

    if [ -n "$data" ]; then
        curl -s -X "$method" \
            -H "Authorization: Bearer $CLERK_SECRET_KEY" \
            -H "Content-Type: application/json" \
            "https://api.clerk.com/v1${endpoint}" \
            -d "$data"
    else
        curl -s -X "$method" \
            -H "Authorization: Bearer $CLERK_SECRET_KEY" \
            "https://api.clerk.com/v1${endpoint}"
    fi
}

Output Rules

  • Target ≤50 lines per script output
  • Use jq to extract only needed fields
  • Never dump full API responses

Phase 1: Discovery

#!/bin/bash
echo "=== User Count ==="
clerk_api GET "/users/count" | jq '{total_users: .total_count}'

echo ""
echo "=== Recent Users ==="
clerk_api GET "/users?limit=20&order_by=-created_at" \
    | jq -r '.[] | "\(.id[0:16])\t\(.email_addresses[0].email_address // "no-email")\t\(.created_at | . / 1000 | strftime("%Y-%m-%d"))"' \
    | column -t | head -20

echo ""
echo "=== Organizations ==="
clerk_api GET "/organizations?limit=20" \
    | jq -r '.data[] | "\(.id[0:16])\t\(.name)\t\(.members_count) members\t\(.created_at | . / 1000 | strftime("%Y-%m-%d"))"' \
    | column -t | head -15

echo ""
echo "=== Active Sessions ==="
clerk_api GET "/sessions?status=active&limit=20" \
    | jq -r '.data[] | "\(.id[0:16])\t\(.user_id[0:16])\t\(.status)\t\(.last_active_at | . / 1000 | strftime("%Y-%m-%d %H:%M"))"' \
    | head -15

Phase 2: Analysis

User Health

#!/bin/bash
echo "=== User Growth (sign-up method) ==="
clerk_api GET "/users?limit=200&order_by=-created_at" \
    | jq -r '[.[] | .external_accounts[0].provider // "email"] | group_by(.) | map({(.[0]): length}) | add'

echo ""
echo "=== Users Without Verified Email ==="
clerk_api GET "/users?limit=100" \
    | jq -r '[.[] | select(.email_addresses | all(.verification.status != "verified"))] | length | "Unverified emails: \(.)"'

echo ""
echo "=== Users with 2FA Enabled ==="
clerk_api GET "/users?limit=200" \
    | jq -r '[.[] | select(.two_factor_enabled == true)] | length | "2FA enabled: \(.)"'

echo ""
echo "=== Banned/Locked Users ==="
clerk_api GET "/users?limit=200" \
    | jq -r '[.[] | select(.banned == true or .locked == true)] | length | "Banned/Locked: \(.)"'

Organization Analytics

#!/bin/bash
echo "=== Organization Summary ==="
clerk_api GET "/organizations?limit=50" \
    | jq '{
        total_orgs: (.data | length),
        total_members: (.data | map(.members_count) | add),
        avg_members: (.data | map(.members_count) | if length > 0 then add / length | floor else 0 end)
    }'

echo ""
echo "=== Largest Organizations ==="
clerk_api GET "/organizations?limit=50&order_by=-members_count" \
    | jq -r '.data[] | "\(.name)\t\(.members_count) members\t\(.pending_invitations_count) pending"' \
    | head -10

echo ""
echo "=== Pending Invitations ==="
clerk_api GET "/invitations?status=pending&limit=20" \
    | jq -r '.data[] | "\(.email_address)\t\(.status)\t\(.created_at | . / 1000 | strftime("%Y-%m-%d"))"' \
    | head -15

Output Format

=== Clerk Instance ===
Total Users: <n>  Organizations: <n>

--- Auth Health ---
2FA Enabled: <n>  Unverified: <n>  Banned: <n>

--- Sign-up Methods ---
email: <n>  google: <n>  github: <n>

--- Organizations ---
Total: <n>  Avg Members: <n>  Pending Invites: <n>

Anti-Hallucination Rules

  1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
  2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
  3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
  4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
  5. ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.

Counter-Rationalizations

ShortcutCounterWhy
"I'll skip discovery and check known resources"Always run Phase 1 discovery firstResource names change, new resources appear — assumed names cause errors
"The user only asked for a quick check"Follow the full discovery → analysis flowQuick checks miss critical issues; structured analysis catches silent failures
"Default configuration is probably fine"Audit configuration explicitlyDefaults often leave logging, security, and optimization features disabled
"Metrics aren't needed for this"Always check relevant metrics when availableAPI/CLI responses show current state; metrics reveal trends and intermittent issues
"I don't have access to that"Try the command and report the actual errorAssumed permission failures prevent useful investigation; actual errors are informative

Common Pitfalls

  • Timestamps: Clerk uses Unix milliseconds, not seconds — divide by 1000 for date conversion
  • Pagination: Use limit and offset; check response array length for more pages
  • Rate limits: 20 requests/10 seconds for backend API
  • User IDs: Prefixed with user_, org IDs with org_
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 193kUpdated Claude CodeCodexVerifiedInstall