Optionen-Kontext
Benutzereingabe: $ARGUMENTS
KRITISCH: Obligatorische Prüfungen VOR JEDER Schreibanfrage
Vor JEDER POST / PATCH / PUT / DELETE-Anfrage MÜSSEN Sie ALLE folgenden Schritte in Ihrer Antwort ausführen:
-
CLERK_SECRET_KEY prüfen — stellen Sie sicher, dass er gesetzt ist:
echo $CLERK_SECRET_KEY | head -c 10Falls leer, anhalten und den Benutzer fragen. Fahren Sie ohne gültigen Schlüssel nicht fort.
-
CLERK_BAPI_SCOPES prüfen — ausführen:
echo $CLERK_BAPI_SCOPESDie Ausgabe inspizieren. Wenn Bereiche fehlen oder die erforderliche Schreibberechtigung nicht enthalten, teilen Sie dem Benutzer mit: „Dies ist ein Schreibvorgang und Ihre aktuellen Berechtigungen könnten ihn nicht erlauben. Erneut mit --admin ausführen, um zu umgehen?“ Versuchen Sie NICHT die Anfrage und scheitern Sie — fragen Sie zuerst.
-
Bei DELETE-Anfragen: warnen Sie explizit, dass die Aktion UNWIDERRUFLICH ist, und listen Sie genau auf, welche Daten dauerhaft zerstört werden (Benutzerdatensatz, alle Sitzungen, alle Mitgliedschaften, alle zugehörigen Daten). Fordern Sie eine ausdrückliche Bestätigung an, bevor Sie fortfahren. Diese Warnung ist PFLICHT — überspringen Sie sie niemals.
-
Bei Metadaten-Operationen: erklären Sie immer, welcher Metadaten-Typ verwendet wird und warum (siehe Abschnitt Metadaten-Typen weiter unten).
FAST PATH: Häufige Operationen (direkt verwenden, kein Spezifikationsabruf nötig)
Führen Sie für die folgenden Operationen keinen Spezifikationsabruf durch und führen Sie sie sofort mit diesen genauen Vorlagen aus. Ersetzen Sie $CLERK_SECRET_KEY, $USER_ID, $ORG_ID, $EMAIL nach Bedarf aus dem Kontext des Benutzers.
Organisation erstellen + Mitglied einladen (zweistufig)
# Schritt 1 — Organisation erstellen
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))"
# Schritt 2 — Organisations-ID extrahieren
ORG_ID=$(echo "$ORG" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
# Schritt 3 — Mitglied mit Rolle einladen
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))"
Rollen: Verwenden Sie "org:admin" oder "org:member" (immer mit org: voranstellen).
SDK-Äquivalent (für Next.js / TypeScript-Projekte mit @clerk/nextjs oder @clerk/backend)
import { clerkClient } from '@clerk/nextjs/server'
// ODER bei direkter Verwendung von @clerk/backend:
// import { createClerkClient } from '@clerk/backend'
// const clerkClient = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })
// Schritt 1: Organisation erstellen
const org = await clerkClient.organizations.createOrganization({
name: 'Acme Corp',
createdBy: userId, // erforderlich — die ID des Benutzers, der die Org erstellt
})
// Schritt 2: Mitglied in die Org einladen
const invitation = await clerkClient.organizations.createOrganizationInvitation({
organizationId: org.id,
emailAddress: '[email protected]',
role: 'org:admin', // oder 'org:member'
})
Benutzer-Metadaten aktualisieren
Erklären Sie immer die drei Metadaten-Typen, bevor Sie fragen, welcher verwendet werden soll:
| Typ | Feld | Lesbar von | Schreibbar von | Verwendung für |
|---|---|---|---|---|
| Öffentlich | public_metadata | Client + Server | Nur Server | Tarifstufe, Rollen, Feature-Flags, die das Frontend liest |
| Privat | private_metadata | Nur Server | Nur Server | Stripe-IDs, Compliance-Flags, interne Bezeichner |
| Unsicher | unsafe_metadata | Client + Server | Client + Server | Flüchtiger UI-Zustand, Onboarding-Schritte (client-schreibbar — sensible Daten vermeiden) |
Für plan: 'pro' und onboarded: true — public_metadata verwenden (frontend-lesbar, server-schreibbar):
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'Aktualisierter Benutzer {d[\"id\"]}: public_metadata={d.get(\"public_metadata\")}')"
SDK-Äquivalent:
import { clerkClient } from '@clerk/nextjs/server'
// ODER: import { createClerkClient } from '@clerk/backend'
await clerkClient.users.updateUser(userId, {
publicMetadata: { plan: 'pro', onboarded: true }, // lesbar vom Client, schreibbar nur durch Server
// privateMetadata: { stripeId: 'cus_xxx' }, // nur Server: lesen UND schreiben
// unsafeMetadata: { step: 'welcome' }, // client-schreibbar, sensible Daten vermeiden
})
Hinweis: Die REST-API verwendet snake_case (public_metadata). Das SDK verwendet camelCase (publicMetadata).
Benutzer auflisten (letzte 7 Tage)
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'Gefundene Benutzer: {len(data)}')
for u in data:
print(f' {u[\"id\"]}: {u.get(\"email_addresses\", [{}])[0].get(\"email_address\", \"keine E-Mail\")}')
else:
print(json.dumps(data, indent=2))
"
Benutzer löschen (Bestätigung erforderlich)
# NUR nach expliziter Benutzerbestätigung ausführen
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'Gelöscht: {d}')"
Clerk Backend API — Vollständige Endpunkt-Referenz
Basis-URL: https://api.clerk.com/v1
Auth: Authorization: Bearer $CLERK_SECRET_KEY bei jeder Anfrage.
Benutzer
Benutzer auflisten
GET /v1/users
Abfrageparameter: limit (max 500, Standard 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 Bereich: gt:TIMESTAMP oder lt:TIMESTAMP in Unix ms)
Gibt zurück: Array von User-Objekten
Benutzer abrufen
GET /v1/users/{user_id}
Gibt zurück: User-Objekt
Benutzer aktualisieren
PATCH /v1/users/{user_id}
Body (JSON, snake_case): { public_metadata, private_metadata, unsafe_metadata, first_name, last_name, username, ... }
Benutzer löschen — UNWIDERRUFLICH
DELETE /v1/users/{user_id}
Zerstört: Benutzerdatensatz, alle Sitzungen, alle Mitgliedschaften, alle zugehörigen Daten
Gibt zurück: { id, object, deleted: true }
Warnen Sie den Benutzer immer, dass dies dauerhaft ist, und bestätigen Sie vor dem Fortfahren.
Organisationen
Organisation erstellen
POST /v1/organizations
Body: { name: string, created_by: string (user_id), public_metadata?, private_metadata?, max_allowed_memberships? }
Gibt zurück: Organization-Objekt mit { id, name, slug, ... }
Organisationen auflisten
GET /v1/organizations
Abfrageparameter: limit, offset, query, order_by
Mitglied einladen
POST /v1/organizations/{organization_id}/invitations
Body: { email_address: string, role: string ("org:admin" oder "org:member"), public_metadata?, private_metadata? }
Gibt zurück: OrganizationInvitation-Objekt
So führen Sie Anfragen aus
Führen Sie Anfragen IMMER mit direkten curl-Befehlen aus. Verwenden Sie die Spezifikations-Extraktionsskripte (api-specs-context.sh, extract-tags.js, extract-endpoint-detail.sh), um Endpunkte zu entdecken, aber tätigen Sie die eigentlichen API-Aufrufe mit curl. Verwenden Sie NICHT scripts/execute-request.sh — es ist ein lokaler Dev-Helfer, nicht für die Agentenverwendung.
Vorlage für GET-Anfragen:
curl -s "https://api.clerk.com/v1${PATH}${QUERY_STRING}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY"
Vorlage für POST/PATCH-Anfragen:
curl -s -X ${METHOD} "https://api.clerk.com/v1${PATH}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '${BODY_JSON}'
Vorlage für DELETE-Anfragen:
curl -s -X DELETE "https://api.clerk.com/v1${PATH}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY"
Nach Erhalt der Antwort: Parsen und klar anzeigen. Verwenden Sie python3 -c "import sys,json; data=json.load(sys.stdin); print(json.dumps(data, indent=2))" zum hübschen Drucken von JSON. Extrahieren Sie Schlüsselfelder (id, email, name, etc.) und fassen Sie sie für den Benutzer zusammen.
API-Spezifikationskontext
Bevor Sie etwas außerhalb des FAST PATH tun, rufen Sie die verfügbaren Spezifikationsversionen und Tags ab, indem Sie ausführen:
bash scripts/api-specs-context.sh
Verwenden Sie die Ausgabe, um die neueste Version und die verfügbaren Tags zu ermitteln.
Caching: Wenn Sie den Spezifikationskontext bereits früher in diesem Gespräch abgerufen haben, rufen Sie ihn NICHT erneut ab. Verwenden Sie die Version und die Tags aus dem vorherigen Aufruf wieder.
Regeln
- Verwenden Sie für häufige Operationen (Benutzer auflisten, Org erstellen, einladen, Metadaten aktualisieren, Benutzer löschen) den FAST PATH oben — rufen Sie NICHT zuerst Spezifikationen ab.
- Ignorieren Sie immer Endpunkte/Schemata, die sich auf
platformbeziehen. - Bestätigen Sie immer vor der Durchführung von Schreibanfragen (POST/PUT/PATCH/DELETE).
- Warnen Sie bei DELETE-Operationen den Benutzer immer, dass die Aktion unwiderruflich ist, und erwähnen Sie, welche Daten verloren gehen (Benutzerdatensatz, Sitzungen, Mitgliedschaften). Diese Warnung ist PFLICHT — überspringen Sie sie niemals.
- Überprüfen Sie bei Schreiboperationen (POST/PUT/PATCH/DELETE)
CLERK_BAPI_SCOPES, bevor Sie die Anfrage versuchen. Wenn sie fehlen oder unzureichend sind, fragen Sie den Benutzer direkt. Versuchen Sie NICHT und scheitern Sie — fragen Sie vor der Ausführung. Diese Prüfung ist PFLICHT. - Erklären Sie bei Metadaten-Operationen immer alle drei Typen (öffentlich, privat, unsicher) und empfehlen Sie den geeigneten.
- Paginierung: Verwenden Sie immer
limit+offsetund erwähnen Sie, dass Ergebnisse für große Datensätze paginiert sein können. - Verwenden Sie direkte curl-Befehle für alle API-Aufrufe — verwenden Sie niemals
scripts/execute-request.sh.
Ratenbegrenzungen & Fallstricke
Ratenbegrenzungen
| Umgebung | Limit |
|---|---|
| Produktion | 1.000 Anfragen / 10 Sekunden |
| Entwicklung | 100 Anfragen / 10 Sekunden |
| Einzeleinladungen | 100 / Stunde |
| Masseneinladungen | 25 / Stunde |
| Organisationseinladungen | 250 / Stunde |
| Frontend-API Anmeldeerstellung | 5 / 10 Sekunden |
| Frontend-API Anmeldeversuche | 3 / 10 Sekunden |
| Benutzer auflisten max. pro Seite | 500 |
currentUser() führt einen echten API-Aufruf aus, der auf die Ratenbegrenzungen angerechnet wird. Verwenden Sie auth() nur für die Sitzungsansprüche — es liest aus dem Token ohne API-Aufruf.
Metadaten-Überschreibungen (keine Zusammenführungen)
updateUser({ publicMetadata: { role: 'admin' } }) ERSETZT alle öffentlichen Metadaten, führt sie nicht zusammen. Um ein Feld hinzuzufügen, ohne vorhandene Daten zu verlieren: zuerst lesen, verteilen, dann schreiben.
Falsch:
await clerkClient.users.updateUser(userId, { publicMetadata: { newField: 'value' } })
Dies LÖSCHT alle anderen publicMetadata-Felder.
Richtig:
const user = await clerkClient.users.getUser(userId)
await clerkClient.users.updateUser(userId, {
publicMetadata: { ...user.publicMetadata, newField: 'value' },
})
Modi
Bestimmen Sie den aktiven Modus basierend auf der Benutzereingabe im Optionen-Kontext:
| Modus | Auslöser | Verhalten |
|---|---|---|
help | Eingabe ist leer oder enthält nur help / -h / --help | Beispiele zur Verwendung ausgeben (Schritt 0) |
browse | Eingabe ist tags oder ein Tag-Name (z. B. Users) | Alle Tags oder Endpunkte für ein Tag auflisten |
execute | Spezifischer Endpunkt (z. B. GET /users) oder natürlichsprachliche Aktion (z. B. "Benutzer john_doe abrufen") | Endpunkt nachschlagen, Anfrage ausführen |
detail | Endpunkt + help / -h / --help (z. B. GET /users help) | Endpunktschema anzeigen, nicht ausführen |
Ihre Aufgabe
Verwenden Sie standardmäßig die NEUESTE VERSION aus dem API-Spezifikationskontext. Wenn der Benutzer eine andere Version angibt (z. B. --version 2024-10-01), verwenden Sie stattdessen diese Version.
Bestimmen Sie den aktiven Modus und befolgen Sie dann die unten zutreffenden Schritte.
0. Verwendung anzeigen
Modi: Nur help — Überspringen für browse, execute und detail.
Geben Sie dem Benutzer die folgenden Beispiele wörtlich aus:
Durchsuchen
/clerk-backend-api tags — alle Tags auflisten
/clerk-backend-api Users — Endpunkte für das Tag Users durchsuchen
/clerk-backend-api Users version 2025-11-10.yml — mit einer anderen Version durchsuchen
Ausführen
/clerk-backend-api GET /users — alle Benutzer abrufen
/clerk-backend-api get user john_doe — natürlichsprachlich funktioniert auch
/clerk-backend-api POST /invitations — eine Einladung erstellen
Inspizieren
/clerk-backend-api GET /users help — Endpunktschema anzeigen, ohne auszuführen
/clerk-backend-api POST /invitations -h — Anfrage-/Antwortdetails anzeigen
Optionen
--admin — Bereichsbeschränkungen für Schreib-/Löschvorgänge umgehen
--version [Datum], version [Datum] — eine bestimmte Spezifikationsversion verwenden
--help, -h, help — Endpunkt inspizieren anstatt auszuführen
Hier anhalten.
1. Tags abrufen
Modi: browse (wenn die Eingabe tags ist oder kein Tag angegeben wurde) — Überspringen für help, execute und detail.
Wenn eine nicht-neueste Version verwendet wird, Tags für diese Version abrufen:
curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | node scripts/extract-tags.js
Andernfalls verwenden Sie die TAGS, die bereits im API-Spezifikationskontext vorhanden sind.
Teilen Sie Tags in einer Tabelle und fordern Sie den Benutzer auf, eine Abfrage auszuwählen.
2. Tag-Endpunkte abrufen
Modi: browse (wenn ein Tag-Name angegeben ist) — Überspringen für help, execute und detail.
Alle Endpunkte für das identifizierte Tag abrufen:
curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | bash scripts/extract-tag-endpoints.sh "${tag_name}"
Teilen Sie die Ergebnisse (Endpunkte, Schemata, Parameter) mit dem Benutzer.
3. Endpunkt-Details abrufen
Modi: execute, detail — Überspringen für help und browse.
Überprüfen Sie bei natürlichsprachlichen Eingaben im execute-Modus zuerst, ob es