Todos os endpoints autenticados da API ficam sob a base URL
https://apis.cativalab.digital/tenant/api/v2. Você prova quem é com o header Authorization: Bearer cativa_live_... em toda chamada.O que é uma API Key
Uma API Key é uma credencial de longa duração que representa a sua aplicação dentro de um tenant. Diferente do OAuth, não há usuário no meio: a chave já carrega o contexto do tenant e das permissões. Cada chave pertence a um único tenant, então você nunca precisa dizer manualmente qual comunidade está chamando.1
Crie uma API Key no Console
No Console, vá em Developers > API Keys > Create.Dê um nome descritivo (ex: Copie e guarde num cofre de secrets. Não dá para ver de novo. Se perder, gere outra e revogue essa.
Sync HubSpot prod) e clique Create. A chave aparece uma única vez, no formato:2
Exporte a chave como variável de ambiente
Para não colar a chave em cada comando, guarde-a numa variável de ambiente. Os exemplos abaixo leem de
CATIVA_API_KEY.3
Faça seu primeiro request
Pegue os dados do usuário associado à chave. Esse é o endpoint canônico para validar uma credencial: se ele responde A resposta é parecida com esta (schema autoritativo na API Reference):
200, sua chave está válida e apontando para o tenant certo.O tenant é resolvido automaticamente a partir da chave, sem header extra. Cada API Key pertence a um único tenant, então toda chamada autenticada já chega com o contexto correto. Use
customer na resposta como sanity check de que você está no tenant certo.4
Faça uma operação real
Com a chave validada, chame qualquer endpoint autenticado da mesma forma. Por exemplo, buscar um usuário pelo Repare que o exemplo Node já loga o
id:traceId em caso de erro. Adote esse hábito desde o primeiro request. Veja Erros e limites de taxa para o formato completo.5
Pronto
A partir daqui você chama todo o catálogo autenticado com a mesma
Authorization: Bearer cativa_live_....O catálogo público de endpoints está publicado na aba API Reference. Ele inclui criação e lookup de usuários (
/admin/users), atribuição de badges (/admin/membership/badges) e carteira de moedas (/monetization/wallet). Navegue pelas tags para ver o schema de cada request.Boas práticas
Não commite chaves
Não commite chaves
Use variáveis de ambiente (ex:
CATIVA_API_KEY) ou cofres de secrets (Doppler, 1Password Secrets, AWS Secrets Manager). Nunca commite chaves no repositório nem as exponha em frontend.Nomeie suas chaves
Nomeie suas chaves
Use nomes descritivos (
Sync HubSpot prod, CI build, Migração 2026-Q2). Facilita auditar e revogar a chave certa quando precisar.Rotacione periodicamente
Rotacione periodicamente
Recomendamos rotação a cada 90 dias. Se uma chave vazar, revogue imediatamente no Console e gere outra.
Trate erros e faça retry certo
Trate erros e faça retry certo
401 Unauthorized significa credencial inválida ou revogada, não retente sem gerar outra. 403 Forbidden indica chave válida sem permissão para o recurso. Para 429 e 5xx, aplique backoff. Sempre logue o traceId retornado no corpo do erro. Detalhes em Erros e limites de taxa.Próximos passos
Login com a Cativa
Para fluxos com usuário interativo, use OAuth 2.0 com PKCE em vez de API Key.
Erros e limites de taxa
O formato de erro RFC 7807, o catálogo de códigos e como tratar
429.Badges como permissão
Como atribuir badges libera acesso a grupos e cursos.
Webhooks
Receba eventos da comunidade sem ficar consultando a API.
