Quick Start: first API call in 2 minutes

This flow is ideal for scripts, jobs, and server-to-server syncs, anything that doesn’t involve an interactive user. Your application acts as itself, proving who it is with an API Key. If instead you want the end user to authenticate with their community account, use Sign in with Cativa.

Every authenticated API endpoint lives under the base URL https://apis.cativalab.digital/tenant/api/v2. You prove who you are with the Authorization: Bearer cativa_live_... header on every call.

What an API Key is

An API Key is a long-lived credential that represents your application inside a tenant. Unlike OAuth, there’s no user in the middle: the key already carries the tenant and permission context. Each key belongs to a single tenant, so you never need to manually say which community you’re calling.

Create an API Key in the Console

In the Console, go to Developers > API Keys > Create.Give it a descriptive name (e.g. Sync HubSpot prod) and click Create. The key is shown only once, in this format:

cativa_live_8c1d4e2a3b5f4d8a9c6e7f0b1a2d3e4f

Copy it and store it in a secrets vault. You can’t view it again. If you lose it, generate a new one and revoke this one.

Treat the key like a password. It grants access to the entire tenant. Never commit it to your repo and never put it in frontend code.

Export the key as an environment variable

So you don’t paste the key into every command, store it in an environment variable. The examples below read from CATIVA_API_KEY.

export CATIVA_API_KEY="cativa_live_8c1d4e2a3b5f4d8a9c6e7f0b1a2d3e4f"

Make your first request

Fetch the data of the user associated with the key. This is the canonical endpoint to validate a credential: if it returns 200, your key is valid and points to the right tenant.

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

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

import os
import requests

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

using System.Net.Http.Headers;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", apiKey);

var res = await http.GetAsync("https://apis.cativalab.digital/tenant/api/v2/auth/me");
var json = await res.Content.ReadAsStringAsync();
Console.WriteLine(json);

The response looks like this (authoritative schema in the API Reference):

{
  "id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
  "email": "dev@example.com",
  "displayName": "HubSpot Integration",
  "role": "admin",
  "customer": "my-community"
}

The tenant is resolved automatically from the key, with no extra header. Each API Key belongs to a single tenant, so every authenticated call already arrives with the right context. Use customer in the response as a sanity check that you’re on the right tenant.

Make a real operation

With the key validated, call any authenticated endpoint the same way. For example, fetch a user by id:

curl https://apis.cativalab.digital/tenant/api/v2/admin/users/01HQ7Z3X4Y5Z6A7B8C9D0E1F2G \
  -H "Authorization: Bearer $CATIVA_API_KEY"

const userId = '01HQ7Z3X4Y5Z6A7B8C9D0E1F2G';
const res = await fetch(
  `https://apis.cativalab.digital/tenant/api/v2/admin/users/${userId}`,
  { headers: { Authorization: `Bearer ${process.env.CATIVA_API_KEY}` } }
);

if (!res.ok) {
  const err = await res.json();
  console.error('Error', err.status, err.type, err.traceId);
} else {
  const user = await res.json();
  console.log(user);
}

Notice the Node example already logs traceId on error. Adopt that habit from your very first request. See Errors and rate limits for the full format.

That's it

From here you call the entire authenticated catalog with the same Authorization: Bearer cativa_live_....

The public endpoint catalog is published in the API Reference tab. It includes user creation and lookup (/admin/users), badge assignment (/admin/membership/badges), and the coin wallet (/monetization/wallet). Browse the tags to see each request’s schema.

Best practices

Don't commit keys

Use environment variables (e.g. CATIVA_API_KEY) or a secrets vault (Doppler, 1Password Secrets, AWS Secrets Manager). Never commit keys to your repo or expose them in frontend code.

Name your keys

Use descriptive names (Sync HubSpot prod, CI build, Migration 2026-Q2). It makes it easier to audit and revoke the right one.

Rotate periodically

We recommend rotation every 90 days. If a key leaks, revoke it immediately in the Console and generate a new one.

Handle errors and retry correctly

401 Unauthorized means the credential is invalid or revoked, don’t retry without generating a new one. 403 Forbidden indicates a valid key without permission for the resource. For 429 and 5xx, apply backoff. Always log the traceId returned in the error body. Details in Errors and rate limits.

Next steps

Sign in with Cativa

For interactive-user flows, use OAuth 2.0 with PKCE instead of an API Key.

Errors and rate limits

The RFC 7807 error format, the code catalog, and how to handle 429.

Badges as Permissions

How assigning badges provisions access to groups and courses.

Webhooks

Receive community events without polling the API.

Get Started

Concepts

Guides

Webhooks

Changelog

Quick Start: first API call in 2 minutes

What an API Key is

Best practices

Next steps

Sign in with Cativa

Errors and rate limits

Badges as Permissions

Webhooks

​What an API Key is

​Best practices

​Next steps

Sign in with Cativa

Errors and rate limits

Badges as Permissions

Webhooks

What an API Key is

Best practices

Next steps