> ## 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 and Customers

> How Cativa's multi-tenant model exposes (or hides) Customer in integrations.

<Note>
  In most integrations you **don't need to think about tenant explicitly**. Authentication and routing already carry the tenant context, and the API filters data behind the scenes. This page documents the exceptions.
</Note>

## The multi-tenant model

Cativa is a **multi-tenant** platform: every customer's **data is fully isolated** from the rest. There is no data leak between tenants — an API call from one tenant never sees or touches another tenant's data.

```
Cativa (platform)
├── Tenant A
│   ├── Users
│   ├── Spaces, Groups, Posts
│   └── Badges
├── Tenant B
│   ├── Users
│   ├── Spaces, Groups, Posts
│   └── Badges
└── Tenant C ...
```

In the product, "tenant" and "customer" are the same concept. The term **Customer** shows up in billing, commercial communication and is the name used in payloads and the OIDC flow (`{customerName}`); the term **tenant** is used in this guide as a synonym. Treat them as equivalent.

## When you need the customer/tenant

### 1. OIDC flow (Sign in with Cativa)

SSO endpoints carry the **customer slug** in the path: `https://apis.cativalab.digital/tenant/api/v2/sso/{customerName}/authorize`, `/token`, `/userinfo`, etc. The `customerName` is the community's public subdomain — align it with the tenant admin at onboarding.

See [Sign in with Cativa](/en/get-started/quickstart-sign-in) for the OIDC step-by-step.

### 2. Webhooks listening to multiple tenants

If your endpoint receives webhooks from **more than one tenant** (typical for apps serving multiple communities), the payload includes `CustomerId` at the top level so you can route correctly.

```json theme={null}
{
  "CustomerId": "01HQ0ABCDEF1234567890XYZ",
  "BadgeId": "01HQ4ABCDEF1234567890XYZ",
  "BadgeName": "Premium",
  "User": {
    "Id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
    "Email": "mary@example.com",
    "DisplayName": "Mary Smith"
  },
  "ReceivedAt": "2026-05-08T14:32:01Z"
}
```

Use `CustomerId` to figure out which account in your own system should receive the sync. Persist the mapping `customerId -> external_account` at customer onboarding — don't try to derive it on every event.

<Note>
  The exact payload shape for each webhook event is documented on the event's page (e.g. [user\_received\_badge](/en/webhooks/events/user-received-badge)).
</Note>

### 3. Cross-tenant Marketplace OAuth apps

If you are building a **Zapier-style app** that connects Cativa to other tools and serves **many different communities**, the right flow is **OAuth Marketplace**:

1. Each community (tenant) installs your app once.
2. Cativa issues an OAuth token **scoped to that tenant**.
3. You store one token per tenant and use the right token on each call.

<Tip>
  If your use case is "one integration for one specific customer", **use an API Key** — it's simpler. OAuth Marketplace is for distributing the app to third parties.
</Tip>

### 4. Console and admin tooling

Admin endpoints (`/tenants/v1/admin/...`) can only be called with **platform operator** credentials and require an admin JWT. If you are an external API Key integrator, **ignore** this category — it isn't publicly exposed to partners.

## How to discover the current customer

If you need to know which customer your key belongs to (for your own logging or auditing), call:

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

The response includes the `customer` name, the `id` of the user tied to the key and the `role` — useful to record in your own audit trail.

## Next steps

<CardGroup cols={2}>
  <Card title="Identity and Users" icon="user" href="/en/concepts/identity-and-users">
    How the user model maps to your external system.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/en/concepts/webhooks">
    Overview of how to receive events from Cativa, including the `CustomerId` field.
  </Card>
</CardGroup>