Tenants e Customers

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 explica o modelo, mostra como o tenant é resolvido em cada request e documenta as poucas exceções em que o Customer aparece na sua frente.

O conceito: por que multi-tenant

A Cativa é uma plataforma multi-tenant: uma única instância da API serve milhares de comunidades diferentes, e cada uma tem os dados completamente isolados das demais. Uma chamada feita no contexto de um tenant nunca enxerga nem afeta dados de outro. Pense num prédio de apartamentos. A estrutura (elevador, encanamento, fachada) é compartilhada, mas cada apartamento tem porta e chave próprias. Ninguém entra no seu apartamento com a chave do vizinho. Na Cativa, a “estrutura” é a API e a infraestrutura; o “apartamento” é o tenant; a “chave” é a credencial que você usa.

Cativa (plataforma)
├── Tenant A (comunidade "makersday")
│   ├── Usuários
│   ├── Espaços, Grupos, Posts
│   └── Badges
├── Tenant B (comunidade "tradersclub")
│   ├── Usuários
│   ├── Espaços, Grupos, Posts
│   └── Badges
└── Tenant C ...

Customer e tenant são a mesma coisa

No produto, Customer e tenant são o mesmo conceito, vistos de ângulos diferentes:

Customer é o nome comercial/administrativo. Aparece em faturamento, no fluxo OIDC ({customerName}) e no campo customer das respostas.
Tenant é o nome técnico. É a unidade de isolamento de dados.

Trate os dois como sinônimos. Cada Customer tem um slug único (por exemplo, makersday), que também é o subdomínio público da comunidade.

Como o tenant é resolvido em cada request

Você quase nunca envia o tenant “na mão”. O contexto é deduzido pela forma como a requisição chega. Entender isso ajuda a debugar respostas vazias ou 403.

Contexto	Como o tenant é resolvido
App/web em produção	Pelo domínio da requisição (o subdomínio da comunidade) ou pelo header `Cativa-Origin`.
Parceiro via API Key	A própria chave já embute o tenant. Nada mais é necessário.
Login OIDC / SSO	Pelo slug `{customerName}` no path do endpoint SSO.
Webhook que serve vários tenants	Pelo campo `CustomerId` no payload do evento.

A API Key embute o tenant

A chave de parceiro segue o formato:

cativa_{env}_{customer}_{hex}
       │      │          └── segredo aleatório
       │      └── identifica o Customer (tenant)
       └── ambiente (ex.: live, test)

Como o segmento do meio identifica o Customer, uma chave só opera dentro de um tenant. Você não precisa (nem consegue) apontar uma chave para outro tenant. Se você integra várias comunidades, guarde uma chave por tenant e escolha a certa em cada chamada.

A API Key é um segredo. Guarde em variável de ambiente ou cofre de segredos, nunca no código-fonte ou no front-end. Nos exemplos usamos cativa_live_... e YOUR_API_KEY como espaço reservado.

Como descobrir o customer atual

Se você precisa saber a qual customer sua chave pertence (para logs, auditoria ou sanity check no onboarding), chame GET /auth/me. O campo customer traz o slug do tenant.

curl https://apis.cativalab.digital/tenant/api/v2/auth/me \
  -H "Authorization: Bearer cativa_live_..."

const res = await fetch('https://apis.cativalab.digital/tenant/api/v2/auth/me', {
  headers: { Authorization: `Bearer ${process.env.CATIVA_API_KEY}` }
});
const me = await res.json();
console.log(me.customer); // => "makersday"

import os, requests

res = requests.get(
    'https://apis.cativalab.digital/tenant/api/v2/auth/me',
    headers={'Authorization': f"Bearer {os.environ['CATIVA_API_KEY']}"}
)
print(res.json()['customer'])  # => "makersday"

Resposta ilustrativa (campos abreviados):

{
  "id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
  "displayName": "Maria Silva",
  "email": "maria@exemplo.com",
  "role": 1,
  "customer": "makersday"
}

Os JSON de exemplo nesta página são ilustrativos. O schema autoritativo campo a campo fica na aba API Reference (tag Auth).

Quando você lida com o Customer explicitamente

Na maior parte das integrações o tenant é invisível. Estas são as exceções.

Os endpoints SSO usam o slug do customer no path:

https://apis.cativalab.digital/tenant/api/v2/sso/{customerName}/authorize
https://apis.cativalab.digital/tenant/api/v2/sso/{customerName}/token
https://apis.cativalab.digital/tenant/api/v2/sso/{customerName}/userinfo

O customerName é o subdomínio público da comunidade. Alinhe esse valor com o admin do tenant no onboarding. Veja Login com a Cativa para o passo a passo.

2. Webhooks que escutam vários tenants

Se o mesmo endpoint recebe webhooks de mais de um tenant (comum em apps que servem várias comunidades), o payload traz CustomerId na raiz para você rotear.

{
  "CustomerId": "01HQ0ABCDEF1234567890XYZ",
  "BadgeId": "01HQ4ABCDEF1234567890XYZ",
  "BadgeName": "Premium",
  "User": {
    "Id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
    "Email": "maria@exemplo.com",
    "DisplayName": "Maria Silva"
  },
  "ReceivedAt": "2026-05-08T14:32:01Z"
}

Salve o mapeamento customerId -> conta_externa no onboarding do cliente. Não tente deduzir isso a cada evento. O shape de cada evento está documentado na página do webhook (ex.: user_received_badge).

3. Apps cross-tenant no Marketplace OAuth

Se você está construindo um app estilo Zapier que conecta a Cativa a outras ferramentas e serve várias comunidades diferentes, o fluxo correto é o OAuth Marketplace:

Instalação

Cada comunidade (tenant) instala seu app uma vez.

Token por tenant

A Cativa emite um token OAuth escopado para aquele tenant.

Uso

Você guarda um token por tenant e usa o token certo em cada chamada.

Se o seu caso é “uma integração para um cliente específico”, use uma API Key: é mais simples. OAuth Marketplace é para distribuir o app a terceiros.

4. Console e ferramentas administrativas da plataforma

Endpoints de operador da plataforma (/tenants/v1/admin/...) exigem credenciais de operador e JWT de admin da plataforma. Se você é integrador externo via API Key, ignore essa categoria: ela não é exposta publicamente a parceiros.

Erros comuns de contexto de tenant

401 Unauthorized

A credencial está ausente, malformada ou revogada. Confira o header Authorization: Bearer cativa_live_... e se a chave é do ambiente certo (live vs test).

403 Forbidden

A credencial é válida, mas não tem permissão para o recurso, ou você está tentando acessar dado de outro tenant. Lembre: uma chave opera só dentro do próprio tenant. Chame GET /auth/me e confira o campo customer.

Resposta 200 mas vazia ou incompleta

Quase sempre é resolução de tenant errada em produção (domínio ou header Cativa-Origin incorreto), então a API filtra e devolve o conjunto vazio daquele tenant. Confirme o subdomínio/origin da requisição.

Veja Erros e limites de taxa para o contrato completo de erros.

Próximos passos

Identidade e usuários

O modelo User e como ligá-lo ao seu sistema externo.

Webhooks

Como receber eventos da Cativa, incluindo o campo CustomerId.

Comece aqui

Conceitos

Guias

Webhooks

Changelog

O conceito: por que multi-tenant

Customer e tenant são a mesma coisa

Como o tenant é resolvido em cada request

A API Key embute o tenant

Como descobrir o customer atual

Quando você lida com o Customer explicitamente

Erros comuns de contexto de tenant

Próximos passos

Identidade e usuários

Webhooks

​O conceito: por que multi-tenant

​Customer e tenant são a mesma coisa

​Como o tenant é resolvido em cada request

​A API Key embute o tenant

​Como descobrir o customer atual

​Quando você lida com o Customer explicitamente

​Erros comuns de contexto de tenant

​Próximos passos

Identidade e usuários

Webhooks

O conceito: por que multi-tenant

Customer e tenant são a mesma coisa

Como o tenant é resolvido em cada request

A API Key embute o tenant

Como descobrir o customer atual

Quando você lida com o Customer explicitamente

Erros comuns de contexto de tenant

Próximos passos