clerk

1# Clerk
2 
3## Purpose
4Manage users in the user's Clerk application through the Clerk Backend API: list users, look up one user, create users, update names, and delete users. Use when the user mentions their Clerk users.
5 
6## Tooling
7All commands go through `bin/clerk.py`:
8 
9```bash
10bin/clerk.py auth                                                    # verify the secret key
11bin/clerk.py users --limit 25                                        # list users
12bin/clerk.py user --id <user-id>                                     # look up one user
13bin/clerk.py create --email "them@example.com" --first-name Ana      # create a user
14bin/clerk.py update --id <user-id> --last-name Reyes                 # update a user
15bin/clerk.py delete --id <user-id>                                    # delete a user
16```
17 
18## Auth
19- Provider id: `clerk` (credential is collected as `custom.clerk`)
20- Collection: secret key (`sk_...`) via the secure credential flow (`credentials.request_api_access`); found in the Clerk dashboard under API Keys
21- Allowed hosts: `api.clerk.com`
22- Status check: `bin/clerk.py auth` (must return `"ok": true`)
23 
24## Operating Rules
251. Request bodies use snake_case field names (for example `public_metadata`). The Clerk SDKs use camelCase; keep the two conventions separate and never send SDK-style field names to this API.
262. Create, update, and delete are confirmation-gated: confirm the details with the user first, unless standing permission exists.
27…