Contexto de Opções
Prompt do Usuário: $ARGUMENTS
CRÍTICO: Verificações obrigatórias ANTES de cada requisição de escrita
Antes de QUALQUER POST / PATCH / PUT / DELETE, você DEVE fazer TODAS as seguintes verificações na sua resposta:
-
Verificar CLERK_SECRET_KEY — certifique-se de que está definida:
echo $CLERK_SECRET_KEY | head -c 10Se estiver vazia, pare e pergunte ao usuário. Não prossiga sem uma chave válida.
-
Verificar CLERK_BAPI_SCOPES — execute:
echo $CLERK_BAPI_SCOPESInspecione a saída. Se os escopos estiverem faltando ou não incluírem a permissão de escrita necessária, informe ao usuário: "Esta é uma operação de escrita e seus escopos atuais podem não permiti-la. Executar novamente com --admin para ignorar?" NÃO tente a requisição e falhe — pergunte primeiro.
-
Para requisições DELETE: avise explicitamente que a ação é IRREVERSÍVEL e liste exatamente quais dados serão permanentemente destruídos (registro do usuário, todas as sessões, todas as associações, todos os dados associados). Exija confirmação explícita antes de prosseguir. Este aviso é OBRIGATÓRIO — nunca o pule.
-
Para operações de metadados: sempre explique qual tipo de metadado está sendo usado e por quê (veja a seção Tipos de Metadados abaixo).
CAMINHO RÁPIDO: Operações comuns (use diretamente, sem buscar especificações)
Para as operações abaixo, pule a busca de especificações e execute imediatamente usando estes modelos exatos. Substitua $CLERK_SECRET_KEY, $USER_ID, $ORG_ID, $EMAIL conforme necessário do contexto do usuário.
Criar organização + convidar membro (duas etapas)
# Etapa 1 — Criar organização
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))"
# Etapa 2 — Extrair ID da organização
ORG_ID=$(echo "$ORG" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
# Etapa 3 — Convidar membro com função
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))"
Funções: use "org:admin" ou "org:member" (sempre prefixado com org:).
Equivalente SDK (para projetos Next.js / TypeScript com @clerk/nextjs ou @clerk/backend)
import { clerkClient } from '@clerk/nextjs/server'
// OU se estiver usando @clerk/backend diretamente:
// import { createClerkClient } from '@clerk/backend'
// const clerkClient = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })
// Etapa 1: Criar organização
const org = await clerkClient.organizations.createOrganization({
name: 'Acme Corp',
createdBy: userId, // obrigatório — o ID do usuário que está criando a org
})
// Etapa 2: Convidar membro para a org
const invitation = await clerkClient.organizations.createOrganizationInvitation({
organizationId: org.id,
emailAddress: '[email protected]',
role: 'org:admin', // ou 'org:member'
})
Atualizar metadados do usuário
Sempre explique os três tipos de metadados antes de perguntar qual usar:
| Tipo | Campo | Legível por | Editável por | Uso para |
|---|---|---|---|---|
| Público | public_metadata | Cliente + Servidor | Apenas servidor | Plano, funções, flags de recursos que o frontend lê |
| Privado | private_metadata | Apenas servidor | Apenas servidor | IDs Stripe, flags de conformidade, identificadores internos |
| Inseguro | unsafe_metadata | Cliente + Servidor | Cliente + Servidor | Estado de IU efêmero, etapas de onboarding (editável pelo cliente — evite dados sensíveis) |
Para plan: 'pro' e onboarded: true — use public_metadata (legível pelo frontend, editável pelo 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'Usuário atualizado {d[\"id\"]}: public_metadata={d.get(\"public_metadata\")}')"
Equivalente SDK:
import { clerkClient } from '@clerk/nextjs/server'
// OU: import { createClerkClient } from '@clerk/backend'
await clerkClient.users.updateUser(userId, {
publicMetadata: { plan: 'pro', onboarded: true }, // legível pelo cliente, editável apenas pelo servidor
// privateMetadata: { stripeId: 'cus_xxx' }, // leitura e escrita apenas pelo servidor
// unsafeMetadata: { step: 'welcome' }, // editável pelo cliente, evite dados sensíveis
})
Nota: A API REST usa snake_case (public_metadata). O SDK usa camelCase (publicMetadata).
Listar usuários (últimos 7 dias)
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'Encontrados {len(data)} usuários:')
for u in data:
print(f' {u[\"id\"]}: {u.get(\"email_addresses\", [{}])[0].get(\"email_address\", \"sem email\")}')
else:
print(json.dumps(data, indent=2))
"
Excluir usuário (confirmação necessária)
# EXECUTAR APENAS após confirmação explícita do usuário
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'Excluído: {d}')"
Referência Completa de Endpoints da Clerk Backend API
URL Base: https://api.clerk.com/v1
Autenticação: Authorization: Bearer $CLERK_SECRET_KEY em cada requisição.
Usuários
Listar usuários
GET /v1/users
Parâmetros de consulta: limit (máx. 500, padrão 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 (intervalo ISO 8601: gt:TIMESTAMP ou lt:TIMESTAMP em ms Unix)
Retorna: array de objetos User
Obter usuário
GET /v1/users/{user_id}
Retorna: objeto User
Atualizar usuário
PATCH /v1/users/{user_id}
Corpo (JSON, snake_case): { public_metadata, private_metadata, unsafe_metadata, first_name, last_name, username, ... }
Excluir usuário — IRREVERSÍVEL
DELETE /v1/users/{user_id}
Destrói: registro do usuário, todas as sessões, todas as associações, todos os dados associados
Retorna: { id, object, deleted: true }
Sempre avise o usuário que isso é permanente e confirme antes de prosseguir.
Organizações
Criar organização
POST /v1/organizations
Corpo: { name: string, created_by: string (user_id), public_metadata?, private_metadata?, max_allowed_memberships? }
Retorna: objeto Organization com { id, name, slug, ... }
Listar organizações
GET /v1/organizations
Parâmetros de consulta: limit, offset, query, order_by
Convidar membro
POST /v1/organizations/{organization_id}/invitations
Corpo: { email_address: string, role: string ("org:admin" ou "org:member"), public_metadata?, private_metadata? }
Retorna: objeto OrganizationInvitation
Como executar requisições
SEMPRE execute requisições com comandos curl diretos. Use os scripts de extração de especificações (api-specs-context.sh, extract-tags.js, extract-endpoint-detail.sh) para descobrir endpoints, mas faça chamadas de API reais com curl. NÃO use scripts/execute-request.sh — é um auxiliar de desenvolvimento local, não para uso do agente.
Modelo para requisições GET:
curl -s "https://api.clerk.com/v1${PATH}${QUERY_STRING}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY"
Modelo para requisições 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}'
Modelo para requisições DELETE:
curl -s -X DELETE "https://api.clerk.com/v1${PATH}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY"
Após obter a resposta: Analise e exiba claramente. Use python3 -c "import sys,json; data=json.load(sys.stdin); print(json.dumps(data, indent=2))" para formatar JSON. Extraia campos-chave (id, email, nome, etc.) e resuma para o usuário.
Contexto de especificações da API
Antes de fazer qualquer coisa fora do CAMINHO RÁPIDO, busque as versões e tags disponíveis da especificação executando:
bash scripts/api-specs-context.sh
Use a saída para determinar a versão mais recente e as tags disponíveis.
Cache: Se você já buscou o contexto da especificação anteriormente nesta conversa, NÃO o busque novamente. Reutilize a versão e as tags da chamada anterior.
Regras
- Para operações comuns (listar usuários, criar organização, convidar, atualizar metadados, excluir usuário): use o CAMINHO RÁPIDO acima — NÃO busque especificações primeiro.
- Sempre ignore endpoints/esquemas relacionados a
platform. - Sempre confirme antes de realizar requisições de escrita (POST/PUT/PATCH/DELETE).
- Para operações DELETE, sempre avise o usuário que a ação é irreversível e mencione quais dados serão perdidos (registro do usuário, sessões, associações). Este aviso é OBRIGATÓRIO — nunca o pule.
- Para operações de escrita (POST/PUT/PATCH/DELETE), verifique
CLERK_BAPI_SCOPESantes de tentar a requisição. Se estiverem faltando ou forem insuficientes, pergunte ao usuário antecipadamente. NÃO tente e falhe — pergunte antes de executar. Esta verificação é OBRIGATÓRIA. - Para operações de metadados, sempre explique todos os três tipos (público, privado, inseguro) e recomende o apropriado.
- Paginação: sempre use
limit+offsete mencione que os resultados podem ser paginados para grandes conjuntos de dados. - Use comandos
curldiretos para todas as chamadas de API — nunca usescripts/execute-request.sh.
Limites de Taxa e Armadilhas
Limites de Taxa
| Ambiente | Limite |
|---|---|
| Produção | 1.000 requisições / 10 segundos |
| Desenvolvimento | 100 requisições / 10 segundos |
| Convites únicos | 100 / hora |
| Convites em massa | 25 / hora |
| Convites de organização | 250 / hora |
| Criação de login na API Frontend | 5 / 10 segundos |
| Tentativas de login na API Frontend | 3 / 10 segundos |
| Máx. de usuários por página na listagem | 500 |
currentUser() faz uma chamada de API real que conta contra os limites de taxa. Use auth() apenas para as claims da sessão — lê do token sem uma chamada de API.
Sobrescrita de Metadados (Não Mesclagem)
updateUser({ publicMetadata: { role: 'admin' } }) SUBSTITUI todos os metadados públicos, não mescla. Para adicionar um campo sem perder dados existentes: leia primeiro, espalhe, depois escreva.
Errado:
await clerkClient.users.updateUser(userId, { publicMetadata: { newField: 'value' } })
Isso EXCLUI todos os outros campos publicMetadata.
Correto:
const user = await clerkClient.users.getUser(userId)
await clerkClient.users.updateUser(userId, {
publicMetadata: { ...user.publicMetadata, newField: 'value' },
})
Modos
Determine o modo ativo com base no prompt do usuário em Contexto de Opções:
| Modo | Gatilho | Comportamento |
|---|---|---|
help | Prompt está vazio, ou contém apenas help / -h / --help | Imprimir exemplos de uso (etapa 0) |
browse | Prompt é tags, ou um nome de tag (ex. Users) | Listar todas as tags ou endpoints para uma tag |
execute | Endpoint específico (ex. GET /users) ou ação em linguagem natural (ex. "obter usuário john_doe") | Pesquisar endpoint, executar requisição |
detail | Endpoint + help / -h / --help (ex. GET /users help) | Mostrar esquema do endpoint, não executar |
Sua Tarefa
Use a VERSÃO MAIS RECENTE do Contexto de especificações da API por padrão. Se o usuário especificar uma versão diferente (ex. --version 2024-10-01), use essa versão.
Determine o modo ativo, depois siga as etapas aplicáveis abaixo.
0. Imprimir uso
Modos: apenas help — Pule para browse, execute e detail.
Imprima os seguintes exemplos para o usuário textualmente:
Navegar
/clerk-backend-api tags — listar todas as tags
/clerk-backend-api Users — navegar pelos endpoints da tag Users
/clerk-backend-api Users version 2025-11-10.yml — navegar usando uma versão diferente
Executar
/clerk-backend-api GET /users — buscar todos os usuários
/clerk-backend-api get user john_doe — linguagem natural também funciona
/clerk-backend-api POST /invitations — criar um convite
Inspecionar
/clerk-backend-api GET /users help — mostrar esquema do endpoint sem executar
/clerk-backend-api POST /invitations -h — ver detalhes de requisição/resposta
Opções
--admin — ignorar restrições de escopo para escrita/exclusão
--version [date], version [date] — usar uma versão específica da especificação
--help, -h, help — inspecionar endpoint em vez de executar
Pare aqui.
1. Buscar tags
Modos: browse (quando o prompt é tags ou nenhuma tag especificada) — Pule para help, execute e detail.
Se estiver usando uma versão não recente, busque tags para essa versão:
curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | node scripts/extract-tags.js
Caso contrário, use as TAGS já no Contexto de especificações da API.
Compartilhe as tags em uma tabela e peça ao usuário para selecionar uma consulta.
2. Buscar endpoints da tag
Modos: browse (quando um nome de tag é fornecido) — Pule para help, execute e detail.
Busque todos os endpoints para a tag identificada:
curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | bash scripts/extract-tag-endpoints.sh "${tag_name}"
Compartilhe os resultados (endpoints, esquemas, parâmetros) com o usuário.
3. Buscar detalhes do endpoint
Modos: execute, detail — Pule para help e browse.
Para prompts em linguagem natural no modo execute, primeiro verifique se a ação corresponde a uma operação do CAMINHO RÁPIDO. Se sim, execute usando o modelo do CAMINHO RÁPIDO. Caso contrário, busque as especificações e determine o endpoint mais relevante.
[continuação omitida para tradução]