Contexto de opciones
Prompt del usuario: $ARGUMENTS
CRÍTICO: Verificaciones obligatorias antes de CADA solicitud de escritura
Antes de cualquier POST / PATCH / PUT / DELETE, DEBES hacer TODO lo siguiente en tu respuesta:
-
Verificar CLERK_SECRET_KEY — comprueba que esté configurada:
echo $CLERK_SECRET_KEY | head -c 10Si está vacía, detente y pregúntale al usuario. No continúes sin una clave válida.
-
Verificar CLERK_BAPI_SCOPES — ejecuta:
echo $CLERK_BAPI_SCOPESInspecciona la salida. Si faltan alcances o no incluyen el permiso de escritura requerido, dile al usuario: "Esta es una operación de escritura y tus alcances actuales pueden no permitirla. ¿Reejecutar con --admin para omitir?" NO intentes la solicitud y falles: pregunta primero.
-
Para solicitudes DELETE: advierte explícitamente que la acción es IRREVERSIBLE y enumera exactamente qué datos se destruirán permanentemente (registro de usuario, todas las sesiones, todas las membresías, todos los datos asociados). Requiere confirmación explícita antes de continuar. Esta advertencia es OBLIGATORIA: nunca la omitas.
-
Para operaciones de metadatos: explica siempre qué tipo de metadato se está usando y por qué (consulta la sección Tipos de metadatos más abajo).
RUTA RÁPIDA: Operaciones comunes (úsalas directamente, sin necesidad de obtener especificaciones)
Para las siguientes operaciones, omite la obtención de especificaciones y ejecuta inmediatamente usando estas plantillas exactas. Sustituye $CLERK_SECRET_KEY, $USER_ID, $ORG_ID, $EMAIL según sea necesario del contexto del usuario.
Crear organización + invitar miembro (dos pasos)
# Paso 1 — Crear organización
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))"
# Paso 2 — Extraer ID de la organización
ORG_ID=$(echo "$ORG" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
# Paso 3 — Invitar miembro con rol
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: usa "org:admin" o "org:member" (siempre con el prefijo org:).
Equivalente en SDK (para proyectos Next.js / TypeScript con @clerk/nextjs o @clerk/backend)
import { clerkClient } from '@clerk/nextjs/server'
// O si usas @clerk/backend directamente:
// import { createClerkClient } from '@clerk/backend'
// const clerkClient = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })
// Paso 1: Crear organización
const org = await clerkClient.organizations.createOrganization({
name: 'Acme Corp',
createdBy: userId, // requerido — el ID del usuario que crea la organización
})
// Paso 2: Invitar miembro a la organización
const invitation = await clerkClient.organizations.createOrganizationInvitation({
organizationId: org.id,
emailAddress: '[email protected]',
role: 'org:admin', // o 'org:member'
})
Actualizar metadatos de usuario
Explica siempre los tres tipos de metadatos antes de preguntar cuál usar:
| Tipo | Campo | Legible por | Escribible por | Úsalo para |
|---|---|---|---|---|
| Público | public_metadata | Cliente + Servidor | Solo servidor | Nivel de plan, roles, flags de funcionalidad que el frontend lee |
| Privado | private_metadata | Solo servidor | Solo servidor | IDs de Stripe, flags de cumplimiento, identificadores internos |
| Inseguro | unsafe_metadata | Cliente + Servidor | Cliente + Servidor | Estado efímero de la interfaz, pasos de onboarding (escribible por el cliente: evita datos sensibles) |
Para plan: 'pro' y onboarded: true — usa public_metadata (legible por el frontend, escribible por el servidor):
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'Usuario {d[\"id\"]} actualizado: public_metadata={d.get(\"public_metadata\")}')"
Equivalente en SDK:
import { clerkClient } from '@clerk/nextjs/server'
// O: import { createClerkClient } from '@clerk/backend'
await clerkClient.users.updateUser(userId, {
publicMetadata: { plan: 'pro', onboarded: true }, // legible por el cliente, escribible solo por el servidor
// privateMetadata: { stripeId: 'cus_xxx' }, // solo servidor para lectura y escritura
// unsafeMetadata: { step: 'welcome' }, // escribible por el cliente, evita datos sensibles
})
Nota: La API REST usa snake_case (public_metadata). El SDK usa camelCase (publicMetadata).
Listar usuarios (últimos 7 días)
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'Se encontraron {len(data)} usuarios:')
for u in data:
print(f' {u[\"id\"]}: {u.get(\"email_addresses\", [{}])[0].get(\"email_address\", \"sin correo\")}')
else:
print(json.dumps(data, indent=2))
"
Eliminar usuario (confirmación requerida)
# SOLO ejecutar después de la confirmación explícita del usuario
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'Eliminado: {d}')"
Referencia completa de endpoints de la API Backend de Clerk
URL base: https://api.clerk.com/v1
Autenticación: Authorization: Bearer $CLERK_SECRET_KEY en cada solicitud.
Usuarios
Listar usuarios
GET /v1/users
Parámetros de consulta: limit (máx. 500, predet. 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 (rango ISO 8601: gt:TIMESTAMP o lt:TIMESTAMP en ms Unix)
Devuelve: array de objetos User
Obtener usuario
GET /v1/users/{user_id}
Devuelve: objeto User
Actualizar usuario
PATCH /v1/users/{user_id}
Cuerpo (JSON, snake_case): { public_metadata, private_metadata, unsafe_metadata, first_name, last_name, username, ... }
Eliminar usuario — IRREVERSIBLE
DELETE /v1/users/{user_id}
Destruye: registro de usuario, todas las sesiones, todas las membresías, todos los datos asociados
Devuelve: { id, object, deleted: true }
Siempre advierte al usuario que esto es permanente y confirma antes de continuar.
Organizaciones
Crear organización
POST /v1/organizations
Cuerpo: { name: string, created_by: string (user_id), public_metadata?, private_metadata?, max_allowed_memberships? }
Devuelve: objeto Organization con { id, name, slug, ... }
Listar organizaciones
GET /v1/organizations
Parámetros de consulta: limit, offset, query, order_by
Invitar miembro
POST /v1/organizations/{organization_id}/invitations
Cuerpo: { email_address: string, role: string ("org:admin" o "org:member"), public_metadata?, private_metadata? }
Devuelve: objeto OrganizationInvitation
Cómo ejecutar solicitudes
Ejecuta SIEMPRE las solicitudes con comandos curl directos. Usa los scripts de extracción de especificaciones (api-specs-context.sh, extract-tags.js, extract-endpoint-detail.sh) para descubrir endpoints, pero realiza las llamadas reales a la API con curl. NO uses scripts/execute-request.sh — es una ayuda de desarrollo local, no para uso del agente.
Plantilla para solicitudes GET:
curl -s "https://api.clerk.com/v1${PATH}${QUERY_STRING}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY"
Plantilla para solicitudes 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}'
Plantilla para solicitudes DELETE:
curl -s -X DELETE "https://api.clerk.com/v1${PATH}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY"
Después de recibir la respuesta: Analízala y muéstrala claramente. Usa python3 -c "import sys,json; data=json.load(sys.stdin); print(json.dumps(data, indent=2))" para mostrar el JSON formateado. Extrae los campos clave (id, email, nombre, etc.) y resúmelos para el usuario.
Contexto de especificaciones de la API
Antes de hacer cualquier cosa fuera de la RUTA RÁPIDA, obtén las versiones y etiquetas disponibles de la especificación ejecutando:
bash scripts/api-specs-context.sh
Usa la salida para determinar la última versión y las etiquetas disponibles.
Almacenamiento en caché: Si ya obtuviste el contexto de la especificación anteriormente en esta conversación, NO lo obtengas de nuevo. Reutiliza la versión y las etiquetas de la llamada anterior.
Reglas
- Para operaciones comunes (listar usuarios, crear organización, invitar, actualizar metadatos, eliminar usuario): usa la RUTA RÁPIDA anterior — NO obtengas especificaciones primero.
- Ignora siempre los endpoint/esquemas relacionados con
platform. - Confirma siempre antes de realizar solicitudes de escritura (POST/PUT/PATCH/DELETE).
- Para operaciones DELETE, advierte siempre al usuario que la acción es irreversible y menciona qué datos se perderán (registro de usuario, sesiones, membresías). Esta advertencia es OBLIGATORIA: nunca la omitas.
- Para operaciones de escritura (POST/PUT/PATCH/DELETE), verifica
CLERK_BAPI_SCOPESantes de intentar la solicitud. Si faltan o son insuficientes, pregúntale al usuario directamente. NO intentes y falles: pregunta antes de ejecutar. Esta verificación es OBLIGATORIA. - Para operaciones de metadatos, explica siempre los tres tipos (público, privado, inseguro) y recomienda el más adecuado.
- Paginación: usa siempre
limit+offsety menciona que los resultados pueden estar paginados para conjuntos de datos grandes. - Usa comandos
curldirectos para todas las llamadas a la API — nunca usesscripts/execute-request.sh.
Límites de tasa y aspectos a tener en cuenta
Límites de tasa
| Entorno | Límite |
|---|---|
| Producción | 1,000 solicitudes / 10 segundos |
| Desarrollo | 100 solicitudes / 10 segundos |
| Invitaciones individuales | 100 / hora |
| Invitaciones masivas | 25 / hora |
| Invitaciones de organización | 250 / hora |
| Creación de inicio de sesión en Frontend API | 5 / 10 segundos |
| Intentos de inicio de sesión en Frontend API | 3 / 10 segundos |
| Máximo de usuarios por página en lista | 500 |
currentUser() realiza una llamada real a la API que cuenta contra los límites de tasa. Usa auth() para solo las reclamaciones de sesión: lee del token sin una llamada a la API.
Sobrescritura de metadatos (no se fusionan)
updateUser({ publicMetadata: { role: 'admin' } }) REEMPLAZA todos los metadatos públicos, no los fusiona. Para agregar un campo sin perder datos existentes: primero lee, luego expande y después escribe.
Incorrecto:
await clerkClient.users.updateUser(userId, { publicMetadata: { newField: 'value' } })
Esto ELIMINA todos los demás campos de publicMetadata.
Correcto:
const user = await clerkClient.users.getUser(userId)
await clerkClient.users.updateUser(userId, {
publicMetadata: { ...user.publicMetadata, newField: 'value' },
})
Modos
Determina el modo activo según el prompt del usuario en Contexto de opciones:
| Modo | Disparador | Comportamiento |
|---|---|---|
help | El prompt está vacío, o contiene solo help / -h / --help | Muestra ejemplos de uso (paso 0) |
browse | El prompt es tags, o un nombre de etiqueta (ej. Users) | Lista todas las etiquetas o los endpoints de una etiqueta |
execute | Endpoint específico (ej. GET /users) o acción en lenguaje natural (ej. "obtener usuario john_doe") | Busca el endpoint, ejecuta la solicitud |
detail | Endpoint + help / -h / --help (ej. GET /users help) | Muestra el esquema del endpoint, no ejecuta |
Tu tarea
Usa la ÚLTIMA VERSIÓN de Contexto de especificaciones de la API de forma predeterminada. Si el usuario especifica una versión diferente (ej. --version 2024-10-01), usa esa versión.
Determina el modo activo y sigue los pasos aplicables a continuación.
0. Mostrar uso
Modos: solo help — Saltar para browse, execute y detail.
Muestra los siguientes ejemplos al usuario textualmente:
Explorar
/clerk-backend-api tags — listar todas las etiquetas
/clerk-backend-api Users — explorar endpoints de la etiqueta Users
/clerk-backend-api Users version 2025-11-10.yml — explorar usando una versión diferente
Ejecutar
/clerk-backend-api GET /users — obtener todos los usuarios
/clerk-backend-api get user john_doe — funciona también con lenguaje natural
/clerk-backend-api POST /invitations — crear una invitación
Inspeccionar
/clerk-backend-api GET /users help — mostrar esquema del endpoint sin ejecutarlo
/clerk-backend-api POST /invitations -h — ver detalles de solicitud/respuesta
Opciones
--admin — omitir restricciones de alcance para escritura/eliminación
--version [fecha], version [fecha] — usar una versión específica de la especificación
--help, -h, help — inspeccionar el endpoint en lugar de ejecutarlo
Detente aquí.
1. Obtener etiquetas
Modos: browse (cuando el prompt es tags o no se ha especificado una etiqueta) — Saltar para help, execute y detail.
Si se usa una versión que no es la última, obtén las etiquetas para esa versión:
curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | node scripts/extract-tags.js
De lo contrario, usa las ETIQUETAS que ya están en Contexto de especificaciones de la API.
Comparte las etiquetas en una tabla y solicita al usuario que seleccione una consulta.
2. Obtener endpoints de una etiqueta
Modos: browse (cuando se proporciona un nombre de etiqueta) — Saltar para help, execute y detail.
Obtén todos los endpoints de la etiqueta identificada:
curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | bash scripts/extract-tag-endpoints.sh "${tag_name}"
Comparte los resultados (endpoints, esquemas, parámetros) con el usuario.
3. Obtener detalle del endpoint
Modos: execute, detail — Saltar para help y browse.
Para prompts en lenguaje natural en el modo execute, primero verifica si hay una coincidencia directa con la RUTA RÁPIDA; si no, ejecuta:
curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | bash scripts/extract-endpoint-detail.sh "${method}" "${path}"
En el modo detail, muestra la información del esquema sin ejecutar.
4. Ejecutar solicitud
Modos: solo execute — Saltar para help, browse y detail.
Usa las plantillas de curl de la sección Cómo ejecutar solicitudes.
5. Formatear respuesta
Modos: solo execute — Saltar para help, browse y detail.
Analiza la respuesta JSON y preséntala formateada.