Primeiros Passos

Autenticação

Chaves de API

O método de autenticação principal para todas as chamadas programáticas à API é uma chave de API.

Formato

mk_live_<43 caracteres base64url>

Comprimento total: 51 caracteres. Exemplo:

mk_live_aB3xZ9mQwRtYpLkJnVdCeHfIoUsSgA7bWzXc4Eh

Uso

Inclua a chave no header Authorization de cada requisição:

1Authorization: Bearer mk_live_<sua-chave>

Criando chaves de API

No Dashboard → Chaves de API → Criar Chave, ou via API (requer uma sessão Clerk):

$curl -X POST https://dev.muchau.com.br/api/auth/api-keys \
>  -H "Authorization: Bearer <CLERK_SESSION_TOKEN>" \
>  -H "Content-Type: application/json" \
>  -d '{ "name": "production" }'

A chave completa é exibida apenas uma vez no momento da criação. Ela não pode ser recuperada depois. Armazene-a imediatamente em um gerenciador de secrets ou arquivo .env.

Revogando chaves de API

Chaves podem ser revogadas no Dashboard ou via DELETE /api/auth/api-keys/:id. Chaves revogadas são rejeitadas imediatamente.

Tokens de Sessão Clerk (apenas Dashboard)

Um segundo método de autenticação — JWTs do Clerk — é usado apenas pelo frontend do Dashboard para gerenciar a conta (criar/revogar chaves de API, visualizar informações da conta). Esses tokens são emitidos pelo Clerk e não se destinam ao uso direto via API.

Se você está construindo integrações, sempre use chaves de API.

Limites de Taxa

PlanoRequisições por minuto
Starter100
Pro500

Informações sobre limite de taxa são retornadas nos headers da resposta:

1X-RateLimit-Limit: 100
2X-RateLimit-Remaining: 87
3X-RateLimit-Reset: 1720000060

Quando o limite é excedido, a API retorna 429 Too Many Requests.

Boas práticas de segurança

  • Armazene chaves de API em variáveis de ambiente, nunca no código-fonte
  • Use chaves separadas por ambiente (desenvolvimento, staging, produção)
  • Rotacione chaves regularmente via Dashboard → Chaves de API → Rotacionar
  • Configure allowlist de IPs para chaves de produção (em breve)