> ## 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.

# Tenants e Customers

> Como o modelo multi-tenant da Cativa expõe (ou esconde) Customer nas integrações.

<Note>
  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.
</Note>

## 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/tenant/api/v2/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](/pt-BR/get-started/quickstart-sign-in) 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.

```json theme={null}
{
  "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.

<Note>
  O shape exato de cada payload de webhook está documentado na página do evento (ex: [user\_received\_badge](/pt-BR/webhooks/events/user-received-badge)).
</Note>

### 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.

<Tip>
  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.
</Tip>

### 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:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://apis.cativalab.digital/tenant/v1/auth/me \
    -H "Authorization: Bearer cativa_live_..."
  ```

  ```js Node theme={null}
  const res = await fetch('https://apis.cativalab.digital/tenant/v1/auth/me', {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  });
  const me = await res.json();
  console.log(me.customer);
  ```
</CodeGroup>

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

<CardGroup cols={2}>
  <Card title="Identidade e usuários" icon="user" href="/pt-BR/concepts/identity-and-users">
    Como o modelo de usuário se relaciona com o seu sistema externo.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/pt-BR/concepts/webhooks">
    Visão geral de como receber eventos da Cativa, incluindo o campo `CustomerId`.
  </Card>
</CardGroup>