What it does
Clerk Backend REST API explorer and executor. Browse tags, inspect endpoint schemas, and execute authenticated requests
Skills ZICQ category:Agent Workflows clerk-backend-api
Clerk Backend REST API explorer and executor. Browse tags, inspect endpoint schemas, and execute authenticated requests. Use when listing users, managing organizations, or calling any Clerk API endpoint.
Official URL:skills.sh
Intro in this page language first. The official description stays in its original wording; we do not rewrite SKILL.md.
Clerk Backend REST API explorer and executor. Browse tags, inspect endpoint schemas, and execute authenticated requests
listing users, managing organizations, or calling any Clerk API endpoint
Per Agent Skills progressive disclosure: name and description load at startup (~100 tokens); the full SKILL.md body loads when the skill activates; scripts/, references/, and assets/ load only as needed. This file's sections: Options context; CRITICAL: Mandatory checks before EVERY write request; FAST PATH: Common operations (use directly, no spec fetching needed); Create organization + invite member (two-step); Step 1 — Create organization; Step 2 — Extract org ID. It includes spec-recommended sections: step-by-step instructions.
File analysis: besides SKILL.md, the body references scripts/execute-request.sh, scripts/api-specs-context.sh, scripts/extract-tags.js, scripts/extract-tag-endpoints.sh, scripts/extract-endpoint-detail.sh. Those resources load on demand.
Options contextCRITICAL: Mandatory checks before EVERY write requestFAST PATH: Common operations (use directly, no spec fetching needed)Create organization + invite member (two-step)Step 1 — Create organizationStep 2 — Extract org IDStep 3 — Invite member with roleSDK equivalent (for Next.js / TypeScript projects with `@clerk/nextjs` or `@clerk/backend`)Update user metadataList users (last 7 days)Delete user (confirm required)ONLY run after explicit user confirmation
Compatibility:Requires CLERK_SECRET_KEY (sk_*) for Backend API calls. · License:MIT · allowed-tools:Bash, Read, Grep, Skill, WebFetch
Source category:skills.sh agent-skill
nameclerk-backend-apidescriptioncompatibilityallowed-toolsscripts/execute-request.shscripts/api-specs-context.shscripts/extract-tags.jsscripts/extract-tag-endpoints.shscripts/extract-endpoint-detail.shThese paths are extracted from the text. Check the upstream package to verify the files exist.
Invocation syntax and available tools depend on your Agent client. Client integration guide ↗
Choose the target agent and installation scope, keep referenced package files, then verify the skill appears in the client's catalog.
This skill references supporting files. Retrieve the complete directory from the source; copying SKILL.md alone may leave missing dependencies.
Copy these instructions to a compatible agent and confirm the target directory matches your client.
Install the agent skill "clerk-backend-api" into my project. The full SKILL.md and official description are at https://zicq.com/en/skills/skl-0f1f97fe8c16d375-Clerk-Backend-Api.html Save it as .cursor/skills/clerk-backend-api/SKILL.md or .claude/skills/clerk-backend-api/SKILL.md and keep the frontmatter name and description exactly as-is. This skill also ships scripts/, references/, or assets/ — fetch the whole folder from https://github.com/clerk/skills instead of creating only a SKILL.md.
Requires Node.js and npx. First inspect the repository's skill list to confirm the name.
npx skills add 'https://github.com/clerk/skills' --list
npx skills add 'https://github.com/clerk/skills' --skill 'clerk-backend-api'
The CLI lets you choose the agent interactively. The default scope is the project; use -g for user scope. Confirm package availability with the discovery command, then use npx skills list to inspect installed skills.
User Prompt: $ARGUMENTS
Before ANY POST / PATCH / PUT / DELETE, you MUST do ALL of the following in your response:
Check CLERK_SECRET_KEY — verify it is set:
echo $CLERK_SECRET_KEY | head -c 10
If empty, stop and ask the user. Do not proceed without a valid key.
Check CLERK_BAPI_SCOPES — run:
echo $CLERK_BAPI_SCOPES
Inspect the output. If scopes are missing or do not include the required write permission, tell the user: "This is a write operation and your current scopes may not allow it. Rerun with --admin to bypass?" Do NOT attempt the request and fail — ask first.
For DELETE requests: warn explicitly that the action is IRREVERSIBLE and list exactly what data will be permanently destroyed (user record, all sessions, all memberships, all associated data). Require explicit confirmation before proceeding. This warning is MANDATORY — never skip it.
For metadata operations: always explain which metadata type is being used and why (see Metadata types section below).
For the operations below, skip spec fetching and execute immediately using these exact templates. Substitute $CLERK_SECRET_KEY, $USER_ID, $ORG_ID, $EMAIL as needed from the user's context.
# Step 1 — Create organization
ORG=$(curl -s -X POST "https://api.clerk.com/v1/organizations" \
-H "Authorization: Bearer $CLERK_SECRET_KEY" \
-H "Content-Type: application/json" \
-d "{\"name\": \"Acme Corp\", \"created_by\": \"$USER_ID\"}")
echo "$ORG" | python3 -c "import sys,json; d=json.load(sys.stdin); print(json.dumps(d, indent=2))"
# Step 2 — Extract org ID
ORG_ID=$(echo "$ORG" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
# Step 3 — Invite member with role
curl -s -X POST "https://api.clerk.com/v1/organizations/${ORG_ID}/invitations" \
-H "Authorization: Bearer $CLERK_SECRET_KEY" \
-H "Content-Type: application/json" \
-d "{\"email_address\": \"[email protected]\", \"role\": \"org:admin\"}" \
| python3 -c "import sys,json; print(json.dumps(json.load(sys.stdin), indent=2))"
Roles: use "org:admin" or "org:member" (always prefix with org:).
@clerk/nextjs or @clerk/backend)import { clerkClient } from '@clerk/nextjs/server'
// OR if using @clerk/backend directly:
// import { createClerkClient } from '@clerk/backend'
// const clerkClient = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })
// Step 1: Create organization
const org = await clerkClient.organizations.createOrganization({
name: 'Acme Corp',
createdBy: userId, // required — the ID of the user creating the org
})
// Step 2: Invite member to the org
const invitation = await clerkClient.organizations.createOrganizationInvitation({
organizationId: org.id,
emailAddress: '[email protected]',
role: 'org:admin', // or 'org:member'
})
Always explain the three metadata types before asking which to use:
| Type | Field | Readable by | Writable by | Use for |
|------|-------|-------------|-------------|---------|
| Public | public_metadata | Client + Server | Server only | Plan tier, roles, feature flags the frontend reads |
| Private | private_metadata | Server only | Server only | Stripe IDs, compliance flags, internal identifiers |
| Unsafe | unsafe_metadata | Client + Server | Client + Server | Ephemeral UI state, onboarding steps (client-writable — avoid sensitive data) |
For plan: 'pro' and onboarded: true — use public_metadata (frontend-readable, server-writable):
curl -s -X PATCH "https://api.clerk.com/v1/users/${USER_ID}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"public_metadata": {"plan": "pro", "onboarded": true}}' \
| python3 -c "import sys,json; d=json.load(sys.stdin); print(f'Updated user {d[\"id\"]}: public_metadata={d.get(\"public_metadata\")}')"
SDK equivalent:
import { clerkClient } from '@clerk/nextjs/server'
// OR: import { createClerkClient } from '@clerk/backend'
await clerkClient.users.updateUser(userId, {
publicMetadata: { plan: 'pro', onboarded: true }, // readable by client, writable server-only
// privateMetadata: { stripeId: 'cus_xxx' }, // server-only read AND write
// unsafeMetadata: { step: 'welcome' }, // client-writable, avoid sensitive data
})
Note: REST API uses snake_case (public_metadata). SDK uses camelCase (publicMetadata).
curl -s "https://api.clerk.com/v1/users?limit=100&offset=0&order_by=-created_at&created_at=gt:$(date -d '7 days ago' +%s 2>/dev/null || date -v-7d +%s)000" \
-H "Authorization: Bearer $CLERK_SECRET_KEY" \
| python3 -c "
import sys, json
data = json.load(sys.stdin)
if isinstance(data, list):
print(f'Found {len(data)} users:')
for u in data:
print(f' {u[\"id\"]}: {u.get(\"email_addresses\", [{}])[0].get(\"email_address\", \"no email\")}')
else:
print(json.dumps(data, indent=2))
"
# ONLY run after explicit user confirmation
curl -s -X DELETE "https://api.clerk.com/v1/users/${USER_ID}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY" \
| python3 -c "import sys,json; d=json.load(sys.stdin); print(f'Deleted: {d}')"
Base URL: https://api.clerk.com/v1
Auth: Authorization: Bearer $CLERK_SECRET_KEY on every request.
List users
GET /v1/users
Query params: limit (max 500, default 10), offset, order_by (+/-created_at, +/-updated_at, +/-email_address, +/-web3wallet, +/-first_name, +/-last_name, +/-phone_number, +/-username, +/-last_active_at, +/-last_sign_in_at), email_address[], phone_number[], username[], web3wallet[], user_id[], query, created_at (ISO 8601 range: gt:TIMESTAMP or lt:TIMESTAMP in Unix ms)
Returns: array of User objects
Get user
GET /v1/users/{user_id}
Returns: User object
Update user
PATCH /v1/users/{user_id}
Body (JSON, snake_case): { public_metadata, private_metadata, unsafe_metadata, first_name, last_name, username, ... }
Delete user — IRREVERSIBLE
DELETE /v1/users/{user_id}
Destroys: user record, all sessions, all memberships, all associated data
Returns: { id, object, deleted: true }
Always warn the user this is permanent and confirm before proceeding.
Create organization
POST /v1/organizations
Body: { name: string, created_by: string (user_id), public_metadata?, private_metadata?, max_allowed_memberships? }
Returns: Organization object with { id, name, slug, ... }
List organizations
GET /v1/organizations
Query params: limit, offset, query, order_by
Invite member
POST /v1/organizations/{organization_id}/invitations
Body: { email_address: string, role: string ("org:admin" or "org:member"), public_metadata?, private_metadata? }
Returns: OrganizationInvitation object
ALWAYS execute requests with direct curl commands. Use the spec-extraction scripts (api-specs-context.sh, extract-tags.js, extract-endpoint-detail.sh) to discover endpoints, but make actual API calls with curl. Do NOT use scripts/execute-request.sh — it's a local dev helper, not for agent use.
Template for GET requests:
curl -s "https://api.clerk.com/v1${PATH}${QUERY_STRING}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY"
Template for POST/PATCH requests:
curl -s -X ${METHOD} "https://api.clerk.com/v1${PATH}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '${BODY_JSON}'
Template for DELETE requests:
curl -s -X DELETE "https://api.clerk.com/v1${PATH}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY"
After getting the response: Parse and display it clearly. Use python3 -c "import sys,json; data=json.load(sys.stdin); print(json.dumps(data, indent=2))" to pretty-print JSON. Extract key fields (id, email, name, etc.) and summarize them for the user.
Before doing anything outside the FAST PATH, fetch the available spec versions and tags by running:
bash scripts/api-specs-context.sh
Use the output to determine the latest version and available tags.
Caching: If you already fetched the spec context earlier in this conversation, do NOT fetch it again. Reuse the version and tags from the previous call.
platform.CLERK_BAPI_SCOPES before attempting the request. If missing or insufficient, ask the user upfront. Do NOT attempt and fail — ask before executing. This check is MANDATORY.limit + offset and mention that results may be paginated for large datasets.scripts/execute-request.sh.| Environment | Limit | |-------------|-------| | Production | 1,000 requests / 10 seconds | | Development | 100 requests / 10 seconds | | Single invitations | 100 / hour | | Bulk invitations | 25 / hour | | Org invitations | 250 / hour | | Frontend API sign-in creation | 5 / 10 seconds | | Frontend API sign-in attempts | 3 / 10 seconds | | List users max per page | 500 |
currentUser() makes a real API call that counts against rate limits. Use auth() for just the session claims — it reads from the token without an API call.
updateUser({ publicMetadata: { role: 'admin' } }) REPLACES all public metadata, not merges. To add a field without losing existing data: read first, spread, then write.
Wrong:
await clerkClient.users.updateUser(userId, { publicMetadata: { newField: 'value' } })
This DELETES all other publicMetadata fields.
Right:
const user = await clerkClient.users.getUser(userId)
await clerkClient.users.updateUser(userId, {
publicMetadata: { ...user.publicMetadata, newField: 'value' },
})
Determine the active mode based on the user prompt in Options context:
| Mode | Trigger | Behavior |
|------|---------|----------|
| help | Prompt is empty, or contains only help / -h / --help | Print usage examples (step 0) |
| browse | Prompt is tags, or a tag name (e.g. Users) | List all tags or endpoints for a tag |
| execute | Specific endpoint (e.g. GET /users) or natural language action (e.g. "get user john_doe") | Look up endpoint, execute request |
| detail | Endpoint + help / -h / --help (e.g. GET /users help) | Show endpoint schema, don't execute |
Use the LATEST VERSION from API specs context by default. If the user specifies a different version (e.g. --version 2024-10-01), use that version instead.
Determine the active mode, then follow the applicable steps below.
Modes: help only — Skip for browse, execute, and detail.
Print the following examples to the user verbatim:
Browse
/clerk-backend-api tags — list all tags
/clerk-backend-api Users — browse endpoints for the Users tag
/clerk-backend-api Users version 2025-11-10.yml — browse using a different version
Execute
/clerk-backend-api GET /users — fetch all users
/clerk-backend-api get user john_doe — natural language works too
/clerk-backend-api POST /invitations — create an invitation
Inspect
/clerk-backend-api GET /users help — show endpoint schema without executing
/clerk-backend-api POST /invitations -h — view request/response details
Options
--admin — bypass scope restrictions for write/delete
--version [date], version [date] — use a specific spec version
--help, -h, help — inspect endpoint instead of executing
Stop here.
Modes: browse (when prompt is tags or no tag specified) — Skip for help, execute, and detail.
If using a non-latest version, fetch tags for that version:
curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | node scripts/extract-tags.js
Otherwise, use the TAGS already in API specs context.
Share tags in a table and prompt the user to select a query.
Modes: browse (when a tag name is provided) — Skip for help, execute, and detail.
Fetch all endpoints for the identified tag:
curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | bash scripts/extract-tag-endpoints.sh "${tag_name}"
Share the results (endpoints, schemas, parameters) with the user.
Modes: execute, detail — Skip for help and browse.
For natural language prompts in execute mode, first check if the operation matches a FAST PATH entry above. If it does, skip this step and proceed directly to step 4 using the FAST PATH template.
For other endpoints, identify the matching endpoint by searching the tags in context. Fetch tag endpoints if needed to resolve the exact path and method.
Extract the full endpoint definition:
curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | bash scripts/extract-endpoint-detail.sh "${path}" "${method}"
${path} — e.g. /users/{user_id}${method} — lowercase, e.g. getdetail mode: Share the endpoint definition and schemas with the user. Stop here.
execute mode: Continue to step 4.
Modes: execute only.
scripts/execute-request.sh.Example — list users and parse response:
RESPONSE=$(curl -s "https://api.clerk.com/v1/users?limit=10" \
-H "Authorization: Bearer $CLERK_SECRET_KEY")
echo "$RESPONSE" | python3 -c "
import sys, json
data = json.load(sys.stdin)
if isinstance(data, list):
print(f'Found {len(data)} users:')
for u in data:
print(f' {u[\"id\"]}: {u.get(\"email_addresses\", [{}])[0].get(\"email_address\", \"no email\")}')
else:
print(json.dumps(data, indent=2))
"
clerk-setup - Initial Clerk installclerk-orgs - Manage organizations via APIclerk-webhooks - Real-time event syncAgent Workflows
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that exte…
Agent Workflows
Use the ClawdHub CLI to search, install, update, and publish agent skills from clawdhub.com. Use when you need to fetch new skills on the fl…
Agent Workflows
Orchestrate multi-agent teams with defined roles, task lifecycles, handoff protocols, and review workflows. Use when: (1) Setting up a team …
Agent Workflows
Spec-first, TDD, subagent-driven software development workflow. Use when: (1) building any new feature or app — triggers brainstorm → plan →…