Tenants and Customers

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 explains the model, shows how the tenant is resolved on each request, and documents the few exceptions where Customer surfaces.

The concept: why multi-tenant

Cativa is a multi-tenant platform: a single API instance serves thousands of different communities, and each one has its data fully isolated from the rest. A call made in one tenant’s context never sees or touches another tenant’s data. Think of an apartment building. The structure (elevator, plumbing, facade) is shared, but each apartment has its own door and key. Nobody enters your apartment with the neighbor’s key. In Cativa, the “structure” is the API and infrastructure, the “apartment” is the tenant, and the “key” is the credential you use.

Cativa (platform)
├── Tenant A (community "makersday")
│   ├── Users
│   ├── Spaces, Groups, Posts
│   └── Badges
├── Tenant B (community "tradersclub")
│   ├── Users
│   ├── Spaces, Groups, Posts
│   └── Badges
└── Tenant C ...

Customer and tenant are the same thing

In the product, Customer and tenant are the same concept seen from two angles:

Customer is the commercial/admin name. It shows up in billing, in the OIDC flow ({customerName}), and in the customer field of responses.
Tenant is the technical name. It is the unit of data isolation.

Treat the two as synonyms. Each Customer has a unique slug (for example, makersday), which is also the community’s public subdomain.

How the tenant is resolved on each request

You almost never pass the tenant by hand. The context is inferred from how the request arrives. Understanding this helps you debug empty responses or 403s.

Context	How the tenant is resolved
Production app/web	From the request domain (the community subdomain) or the `Cativa-Origin` header.
Partner via API Key	The key itself embeds the tenant. Nothing else is needed.
OIDC / SSO login	From the `{customerName}` slug in the SSO endpoint path.
Webhook serving many tenants	From the `CustomerId` field in the event payload.

The API Key embeds the tenant

The partner key follows this shape:

cativa_{env}_{customer}_{hex}
       │      │          └── random secret
       │      └── identifies the Customer (tenant)
       └── environment (e.g. live, test)

Because the middle segment identifies the Customer, a key only operates inside one tenant. You cannot (and don’t need to) point a key at another tenant. If you integrate several communities, store one key per tenant and pick the right one on each call.

The API Key is a secret. Store it in an environment variable or secret manager, never in source control or the front-end. Examples use cativa_live_... and YOUR_API_KEY as placeholders.

How to discover the current customer

If you need to know which customer your key belongs to (for logging, auditing, or an onboarding sanity check), call GET /auth/me. The customer field carries the tenant slug.

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"

Illustrative response (fields abbreviated):

{
  "id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
  "displayName": "Mary Smith",
  "email": "mary@example.com",
  "role": 1,
  "customer": "makersday"
}

The sample JSON on this page is illustrative. The authoritative field-by-field schema lives in the API Reference tab (Auth tag).

When you handle Customer explicitly

In most integrations the tenant is invisible. These are the exceptions.

SSO endpoints carry the customer slug in the 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

The customerName is the community’s public subdomain. Align it with the tenant admin at onboarding. See Sign in with Cativa for the step-by-step.

2. Webhooks listening to multiple tenants

If the same 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.

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

Persist the mapping customerId -> external_account at customer onboarding. Don’t derive it on every event. Each event’s shape is documented on the webhook page (e.g. user_received_badge).

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:

Install

Each community (tenant) installs your app once.

Token per tenant

Cativa issues an OAuth token scoped to that tenant.

Use

You store one token per tenant and use the right token on each call.

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.

4. Platform console and admin tooling

Platform operator endpoints (/tenants/v1/admin/...) require operator credentials and a platform admin JWT. If you are an external API Key integrator, ignore this category: it isn’t publicly exposed to partners.

Common tenant-context errors

401 Unauthorized

The credential is missing, malformed, or revoked. Check the Authorization: Bearer cativa_live_... header and that the key is for the right environment (live vs test).

403 Forbidden

The credential is valid but lacks permission for the resource, or you are trying to reach another tenant’s data. Remember: a key operates only inside its own tenant. Call GET /auth/me and check the customer field.

200 but empty or incomplete

Almost always a wrong tenant resolution in production (bad domain or Cativa-Origin header), so the API filters and returns that tenant’s empty set. Confirm the request subdomain/origin.

See Errors and rate limits for the full error contract.

Next steps

Identity and Users

The User model and how to tie it to your external system.

Webhooks

How to receive events from Cativa, including the CustomerId field.

Get Started

Concepts

Guides

Webhooks

Changelog

The concept: why multi-tenant

Customer and tenant are the same thing

How the tenant is resolved on each request

The API Key embeds the tenant

How to discover the current customer

When you handle Customer explicitly

Common tenant-context errors

Next steps

Identity and Users

Webhooks

​The concept: why multi-tenant

​Customer and tenant are the same thing

​How the tenant is resolved on each request

​The API Key embeds the tenant

​How to discover the current customer

​When you handle Customer explicitly

​Common tenant-context errors

​Next steps

Identity and Users

Webhooks

The concept: why multi-tenant

Customer and tenant are the same thing

How the tenant is resolved on each request

The API Key embeds the tenant

How to discover the current customer

When you handle Customer explicitly

Common tenant-context errors

Next steps