Skip to main content

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.

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.

​
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/social/v1/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 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. 
{
  "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.
The exact payload shape for each webhook event is documented on the event’s 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:
  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.
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. 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: 
curl https://apis.cativalab.digital/social/v1/auth/me \
  -H "Authorization: Bearer cativa_live_..."
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

Identity and Users

How the user model maps to your external system.

Webhooks

Overview of how to receive events from Cativa, including the CustomerId field.