Skip to main content
Esse fluxo é ideal para scripts, jobs e sincronizações server-to-server, qualquer coisa que não envolve um usuário interativo. A sua aplicação age em nome dela mesma, provando quem é com uma API Key. Se em vez disso você quer que o usuário final autentique com a conta dele da comunidade, use Login com a Cativa.
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: Sync HubSpot prod) e clique Create. A chave aparece uma única vez, no formato:
Copie e guarde num cofre de secrets. Não dá para ver de novo. Se perder, gere outra e revogue essa.
Trate a chave como uma senha. Ela concede acesso ao tenant inteiro. Nunca commite no repositório e nunca coloque em código de frontend.
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 200, sua chave está válida e apontando para o tenant certo.
A resposta é parecida com esta (schema autoritativo na API Reference):
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 id:
Repare que o exemplo Node já loga o 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

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.
Use nomes descritivos (Sync HubSpot prod, CI build, Migração 2026-Q2). Facilita auditar e revogar a chave certa quando precisar.
Recomendamos rotação a cada 90 dias. Se uma chave vazar, revogue imediatamente no Console e gere outra.
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.