clerk-backend-api

Options context

User Prompt: $ARGUMENTS

CRITICAL: Mandatory checks before EVERY write request

Before ANY POST / PATCH / PUT / DELETE, you MUST do ALL of the following in your response:

1. 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.

2. 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.

3. 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.

4. For metadata operations: always explain which metadata type is being used and why (see Metadata types section below).

---

FAST PATH: Common operations (use directly, no spec fetching needed)

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.

Create organization + invite member (two-step)

# 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))"