Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.cativa.digital/llms.txt

Use this file to discover all available pages before exploring further.

Na maioria das integrações você não precisa pensar em tenant explicitamente. A autenticação e o roteamento já carregam o contexto do tenant, e a API filtra os dados por baixo dos panos. Esta página documenta as exceções.

​
O modelo multi-tenant

A Cativa é uma plataforma multi-tenant: cada cliente tem seus dados completamente isolados dos demais. Não existe vazamento de dados entre tenants — uma chamada de API feita por um tenant nunca enxerga ou afeta dados de outro. 
Cativa (plataforma)
├── Tenant A
│   ├── Usuários
│   ├── Espaços, Grupos, Posts
│   └── Badges
├── Tenant B
│   ├── Usuários
│   ├── Espaços, Grupos, Posts
│   └── Badges
└── Tenant C ...
No produto, “tenant” e “customer” são o mesmo conceito. O termo Customer aparece em faturamento e comunicações comerciais e é o nome usado nos payloads e no fluxo OIDC ({customerName}); o termo tenant é usado neste guia como sinônimo. Trate-os como equivalentes.

​
Quando você precisa do customer/tenant

​
1. Fluxo OIDC (login com a Cativa)

Os endpoints SSO usam o slug do customer no path: https://apis.cativalab.digital/social/v1/sso/{customerName}/authorize, /token, /userinfo, etc. O customerName é o subdomínio público da comunidade — alinhe com o admin do tenant na hora do onboarding. Veja Login com a Cativa para o passo a passo do OIDC.

​
2. Webhooks que escutam múltiplos tenants

Se você recebe webhooks de mais de um tenant no mesmo endpoint (caso comum em apps que servem várias comunidades), o payload inclui customerId no nível raiz para você rotear corretamente. 
{
  "CustomerId": "01HQ0ABCDEF1234567890XYZ",
  "BadgeId": "01HQ4ABCDEF1234567890XYZ",
  "BadgeName": "Premium",
  "User": {
    "Id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
    "Email": "maria@exemplo.com",
    "DisplayName": "Maria Silva"
  },
  "ReceivedAt": "2026-05-08T14:32:01Z"
}
Use CustomerId para descobrir qual conta do seu sistema deve receber a sincronização. Salve o mapeamento customerId → conta_externa na hora do onboarding do cliente — não tente deduzir isso a cada evento.
O shape exato de cada payload de webhook está documentado na página do evento (ex: user_received_badge).

​
3. Apps cross-tenant no Marketplace OAuth

Se você está construindo um app estilo Zapier que conecta Cativa a outras ferramentas e precisa servir várias comunidades diferentes, o fluxo correto é o OAuth Marketplace:
  1. Cada comunidade (tenant) instala seu app uma vez.
  2. A Cativa emite um token OAuth escopado para aquele tenant.
  3. Você guarda um token por tenant e usa o token correto em cada chamada.
Se seu uso for “uma integração para um cliente específico”, use uma API Key — é mais simples. OAuth Marketplace é para distribuir o app para terceiros.

​
4. Console e ferramentas administrativas

Endpoints administrativos (/tenants/v1/admin/...) só podem ser chamados com credenciais de operador da plataforma e exigem JWT de admin. Se você é integrador externo via API Key, ignore essa categoria — ela não é exposta publicamente para parceiros.

​
Como descobrir o customer atual

Se você precisa saber a qual customer sua chave pertence (para logs ou auditoria do seu lado), chame: 
curl https://apis.cativalab.digital/social/v1/auth/me \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Cativa-Customer: comunidade-do-pedro"
A resposta inclui o nome do customer, o id do usuário associado à chave e o role — útil para gravar no log de auditoria do seu sistema.

​
Próximos passos

Identidade e usuários

Como o modelo de usuário se relaciona com o seu sistema externo.

Webhooks

Visão geral de como receber eventos da Cativa, incluindo o campo CustomerId.