Contexte des options
Prompt utilisateur : $ARGUMENTS
CRITIQUE : Vérifications obligatoires avant TOUTE requête en écriture
Avant tout POST / PATCH / PUT / DELETE, vous DEVEZ effectuer TOUTES les vérifications suivantes dans votre réponse :
-
Vérifier CLERK_SECRET_KEY — confirmez qu'elle est définie :
echo $CLERK_SECRET_KEY | head -c 10Si vide, arrêtez-vous et demandez à l'utilisateur. Ne continuez pas sans une clé valide.
-
Vérifier CLERK_BAPI_SCOPES — exécutez :
echo $CLERK_BAPI_SCOPESInspectez la sortie. Si les autorisations sont manquantes ou n'incluent pas la permission d'écriture requise, dites à l'utilisateur : "Il s'agit d'une opération en écriture et vos autorisations actuelles peuvent ne pas le permettre. Relancer avec --admin pour ignorer ?" Ne tentez PAS la requête pour échouer — demandez d'abord.
-
Pour les requêtes DELETE : prévenez explicitement que l'action est IRRÉVERSIBLE et listez exactement quelles données seront définitivement détruites (enregistrement utilisateur, toutes les sessions, toutes les adhésions, toutes les données associées). Exigez une confirmation explicite avant de continuer. Cet avertissement est OBLIGATOIRE — ne le sautez jamais.
-
Pour les opérations sur les métadonnées : expliquez toujours quel type de métadonnées est utilisé et pourquoi (voir la section Types de métadonnées ci-dessous).
VOIE RAPIDE : Opérations courantes (à utiliser directement, sans récupérer les spécifications)
Pour les opérations ci-dessous, sautez la récupération des spécifications et exécutez immédiatement en utilisant ces modèles exacts. Remplacez $CLERK_SECRET_KEY, $USER_ID, $ORG_ID, $EMAIL selon le contexte de l'utilisateur.
Créer une organisation + inviter un membre (en deux étapes)
# Étape 1 — Créer l'organisation
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))"
# Étape 2 — Extraire l'ID de l'organisation
ORG_ID=$(echo "$ORG" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
# Étape 3 — Inviter un membre avec un rôle
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))"
Rôles : utilisez "org:admin" ou "org:member" (toujours préfixé par org:).
Équivalent SDK (pour les projets Next.js / TypeScript avec @clerk/nextjs ou @clerk/backend)
import { clerkClient } from '@clerk/nextjs/server'
// OU si vous utilisez @clerk/backend directement :
// import { createClerkClient } from '@clerk/backend'
// const clerkClient = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })
// Étape 1 : Créer l'organisation
const org = await clerkClient.organizations.createOrganization({
name: 'Acme Corp',
createdBy: userId, // requis — l'ID de l'utilisateur créant l'org.
})
// Étape 2 : Inviter un membre à l'organisation
const invitation = await clerkClient.organizations.createOrganizationInvitation({
organizationId: org.id,
emailAddress: '[email protected]',
role: 'org:admin', // ou 'org:member'
})
Mettre à jour les métadonnées d'un utilisateur
Expliquez toujours les trois types de métadonnées avant de demander lequel utiliser :
| Type | Champ | Accessible en lecture par | Accessible en écriture par | Utilisation pour |
|---|---|---|---|---|
| Public | public_metadata | Client + Serveur | Serveur uniquement | Niveau d'abonnement, rôles, fonctionnalités lues par le frontend |
| Privé | private_metadata | Serveur uniquement | Serveur uniquement | IDs Stripe, indicateurs de conformité, identifiants internes |
| Non sécurisé | unsafe_metadata | Client + Serveur | Client + Serveur | État UI éphémère, étapes d'intégration (accessible en écriture par le client — évitez les données sensibles) |
Pour plan: 'pro' et onboarded: true — utilisez public_metadata (accessible en lecture par le frontend, accessible en écriture par le serveur) :
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'Utilisateur mis à jour {d[\"id\"]} : public_metadata={d.get(\"public_metadata\")}')`"
Équivalent SDK :
import { clerkClient } from '@clerk/nextjs/server'
// OU : import { createClerkClient } from '@clerk/backend'
await clerkClient.users.updateUser(userId, {
publicMetadata: { plan: 'pro', onboarded: true }, // accessible en lecture par le client, écriture réservée au serveur
// privateMetadata: { stripeId: 'cus_xxx' }, // lecture ET écriture réservées au serveur
// unsafeMetadata: { step: 'welcome' }, // accessible en écriture par le client, évitez les données sensibles
})
Remarque : L'API REST utilise snake_case (public_metadata). Le SDK utilise camelCase (publicMetadata).
Lister les utilisateurs (7 derniers jours)
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' {len(data)} utilisateurs trouvés :')
for u in data:
print(f' {u[\"id\"]} : {u.get(\"email_addresses\", [{}])[0].get(\"email_address\", \"aucun email\")}')
else:
print(json.dumps(data, indent=2))
"
Supprimer un utilisateur (confirmation requise)
# À exécuter UNIQUEMENT après confirmation explicite de l'utilisateur
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'Supprimé : {d}')"
Référence complète des endpoints de l'API Clerk Backend
URL de base : https://api.clerk.com/v1
Authentification : Authorization: Bearer $CLERK_SECRET_KEY sur chaque requête.
Utilisateurs
Lister les utilisateurs
GET /v1/users
Paramètres de requête : limit (max 500, défaut 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 (plage ISO 8601 : gt:TIMESTAMP ou lt:TIMESTAMP en ms Unix)
Retourne : tableau d'objets User
Obtenir un utilisateur
GET /v1/users/{user_id}
Retourne : objet User
Mettre à jour un utilisateur
PATCH /v1/users/{user_id}
Corps (JSON, snake_case) : { public_metadata, private_metadata, unsafe_metadata, first_name, last_name, username, ... }
Supprimer un utilisateur — IRRÉVERSIBLE
DELETE /v1/users/{user_id}
Détruit : enregistrement utilisateur, toutes les sessions, toutes les adhésions, toutes les données associées
Retourne : { id, object, deleted: true }
Avertissez toujours l'utilisateur que c'est permanent et confirmez avant de continuer.
Organisations
Créer une organisation
POST /v1/organizations
Corps : { name: string, created_by: string (user_id), public_metadata?, private_metadata?, max_allowed_memberships? }
Retourne : objet Organization avec { id, name, slug, ... }
Lister les organisations
GET /v1/organizations
Paramètres de requête : limit, offset, query, order_by
Inviter un membre
POST /v1/organizations/{organization_id}/invitations
Corps : { email_address: string, role: string ("org:admin" ou "org:member"), public_metadata?, private_metadata? }
Retourne : objet OrganizationInvitation
Comment exécuter les requêtes
Exécutez TOUJOURS les requêtes avec des commandes curl directes. Utilisez les scripts d'extraction de spécifications (api-specs-context.sh, extract-tags.js, extract-endpoint-detail.sh) pour découvrir les endpoints, mais effectuez les appels API réels avec curl. N'utilisez PAS scripts/execute-request.sh — c'est un outil d'aide au développement local, pas pour un usage par l'agent.
Modèle pour les requêtes GET :
curl -s "https://api.clerk.com/v1${PATH}${QUERY_STRING}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY"
Modèle pour les requêtes POST/PATCH :
curl -s -X ${METHOD} "https://api.clerk.com/v1${PATH}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '${BODY_JSON}'
Modèle pour les requêtes DELETE :
curl -s -X DELETE "https://api.clerk.com/v1${PATH}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY"
Après avoir reçu la réponse : Analysez-la et affichez-la clairement. Utilisez python3 -c "import sys,json; data=json.load(sys.stdin); print(json.dumps(data, indent=2))" pour un affichage JSON joli. Extrayez les champs clés (id, email, name, etc.) et résumez-les pour l'utilisateur.
Contexte des spécifications API
Avant de faire quoi que ce soit en dehors de la VOIE RAPIDE, récupérez les versions disponibles des spécifications et les balises en exécutant :
bash scripts/api-specs-context.sh
Utilisez la sortie pour déterminer la dernière version et les balises disponibles.
Mise en cache : Si vous avez déjà récupéré le contexte des spécifications plus tôt dans cette conversation, ne le récupérez PAS à nouveau. Réutilisez la version et les balises de l'appel précédent.
Règles
- Pour les opérations courantes (lister les utilisateurs, créer une organisation, inviter, mettre à jour les métadonnées, supprimer un utilisateur) : utilisez la VOIE RAPIDE ci-dessus — ne récupérez PAS les spécifications d'abord.
- Ignorez toujours les endpoints/schémas liés à
platform. - Confirmez toujours avant d'effectuer des requêtes en écriture (POST/PUT/PATCH/DELETE).
- Pour les opérations DELETE, avertissez toujours l'utilisateur que l'action est irréversible et mentionnez quelles données seront perdues (enregistrement utilisateur, sessions, adhésions). Cet avertissement est OBLIGATOIRE — ne le sautez jamais.
- Pour les opérations en écriture (POST/PUT/PATCH/DELETE), vérifiez
CLERK_BAPI_SCOPESavant de tenter la requête. Si elles sont manquantes ou insuffisantes, demandez à l'utilisateur directement. Ne tentez PAS et échouez — demandez avant d'exécuter. Cette vérification est OBLIGATOIRE. - Pour les opérations sur les métadonnées, expliquez toujours les trois types (public, privé, non sécurisé) et recommandez celui qui convient.
- Pagination : utilisez toujours
limit+offsetet mentionnez que les résultats peuvent être paginés pour les grands ensembles de données. - Utilisez des commandes curl directes pour tous les appels API — n'utilisez jamais
scripts/execute-request.sh.
Limites de débit et pièges
Limites de débit
| Environnement | Limite |
|---|---|
| Production | 1 000 requêtes / 10 secondes |
| Développement | 100 requêtes / 10 secondes |
| Invitations individuelles | 100 / heure |
| Invitations en masse | 25 / heure |
| Invitations d'organisation | 250 / heure |
| Création de connexion Frontend API | 5 / 10 secondes |
| Tentatives de connexion Frontend API | 3 / 10 secondes |
| Liste d'utilisateurs max par page | 500 |
currentUser() effectue un véritable appel API qui compte dans les limites de débit. Utilisez auth() pour simplement récupérer les revendications de session — il lit à partir du jeton sans appel API.
Les métadonnées sont écrasées (pas fusionnées)
updateUser({ publicMetadata: { role: 'admin' } }) REMPLACE toutes les métadonnées publiques, ne les fusionne pas. Pour ajouter un champ sans perdre les données existantes : lisez d'abord, étendez, puis écrivez.
Mauvais :
await clerkClient.users.updateUser(userId, { publicMetadata: { newField: 'value' } })
Cela SUPPRIME tous les autres champs publicMetadata.
Bon :
const user = await clerkClient.users.getUser(userId)
await clerkClient.users.updateUser(userId, {
publicMetadata: { ...user.publicMetadata, newField: 'value' },
})
Modes
Déterminez le mode actif en fonction du prompt utilisateur dans Contexte des options :
| Mode | Déclencheur | Comportement |
|---|---|---|
help | Le prompt est vide, ou contient uniquement help / -h / --help | Afficher des exemples d'utilisation (étape 0) |
browse | Le prompt est tags, ou un nom de balise (ex. Users) | Lister toutes les balises ou les endpoints pour une balise |
execute | Endpoint spécifique (ex. GET /users) ou action en langage naturel (ex. "obtenir l'utilisateur john_doe") | Chercher l'endpoint, exécuter la requête |
detail | Endpoint + help / -h / --help (ex. GET /users help) | Afficher le schéma de l'endpoint, ne pas exécuter |
Votre tâche
Utilisez la DERNIÈRE VERSION du Contexte des spécifications API par défaut. Si l'utilisateur spécifie une version différente (ex. --version 2024-10-01), utilisez cette version à la place.
Déterminez le mode actif, puis suivez les étapes applicables ci-dessous.
0. Afficher l'utilisation
Modes : help uniquement — Ignorer pour browse, execute et detail.
Affichez les exemples suivants textuellement à l'utilisateur :
Parcourir
/clerk-backend-api tags — lister toutes les balises
/clerk-backend-api Users — parcourir les endpoints de la balise Users
/clerk-backend-api Users version 2025-11-10.yml — parcourir en utilisant une version différente
Exécuter
/clerk-backend-api GET /users — récupérer tous les utilisateurs
/clerk-backend-api get user john_doe — le langage naturel fonctionne aussi
/clerk-backend-api POST /invitations — créer une invitation
Inspecter
/clerk-backend-api GET /users help — afficher le schéma de l'endpoint sans exécuter
/clerk-backend-api POST /invitations -h — voir les détails de la requête/réponse
Options
--admin — ignorer les restrictions de portée pour les écritures/suppressions
--version [date], version [date] — utiliser une version de spécification spécifique
--help, -h, help — inspecter l'endpoint au lieu d'exécuter
Arrêtez-vous ici.
1. Récupérer les balises
Modes : browse (lorsque le prompt est tags ou qu'aucune balise n'est spécifiée) — Ignorer pour help, execute et detail.
Si vous utilisez une version non finale, récupérez les balises pour cette version :
curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | node scripts/extract-tags.js
Sinon, utilisez les BALISES déjà présentes dans le Contexte des spécifications API.
Partagez les balises dans un tableau et demandez à l'utilisateur de sélectionner une requête.
2. Récupérer les endpoints d'une balise
Modes : browse (lorsqu'un nom de balise est fourni) — Ignorer pour help, execute et detail.
Récupérez tous les endpoints pour la balise identifiée :
curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | bash scripts/extract-tag-endpoints.sh "${tag_name}"
Partagez les résultats (endpoints, schémas, paramètres) avec l'utilisateur.
3. Récupérer les détails d'un endpoint
Modes : execute, detail — Ignorer pour help et browse.
Pour les prompts en langage naturel en mode execute, vérifiez d'abord s'il...