Identity and Users

Every integration with Cativa starts with the user. This page describes the User model at the conceptual level, the canonical endpoint for credential validation, and the admin CRUD you use to create, update, and link users to your CRM or ERP.

The User model

Each user belongs to exactly one tenant and is identified by an id (GUID). The same user never exists in two tenants: if the same person is in two communities, those are two distinct records. The most commonly used fields in authenticated responses:

Field	Type	What it is
`id`	GUID	Unique user identifier within the tenant.
`firstName` / `lastName`	string	First and last name.
`displayName`	string	Name shown in the community.
`userName`	string?	Public handle (used in `GET /users/profile/{userName}`).
`email`	string	Login email.
`pictureUrl`	string?	Public profile picture URL.
`role`	enum	Functional role in the community (see table below).
`status`	enum	Account state (see table below).
`badgeId`	GUID?	Highlight badge (the highest-relevance one that drives the menu and CTA).
`coins`	int	User’s coin balance.
`customer`	string	Slug of the tenant the user belongs to.

The detailed contract for each response (exact field names and types) is published in the API Reference tab, under the Users / Auth tags. The JSON on this page is illustrative.

Roles (`role`)

Value	Name	Description
`0`	User	Regular member.
`1`	Admin	Tenant administrator.
`2`	ContentManager	Manages content.
`3`	ContentCreator	Creates content.

Account status (`status`)

Value	Name	Description
`0`	Inactive	Inactive account.
`1`	Active	Active account.
`2`	IncompleteRegister	Incomplete registration.
`3`	PendingConfirmation	Awaiting email confirmation.
`4`	Banned	Banned.
`5`	ForcePasswordChange	Must change password on next login.
`6`	Expired	Access expired.

Every community has a system user with userName = "admin" (internal to the platform). It never appears in listings, searches, or pickers. Ignore it if it shows up in an export.

Validate credentials and discover the associated user

The canonical endpoint for partners to validate a credential and discover the associated user is GET /auth/me. Call it at your integration’s boot and whenever you need to confirm the context.

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

import os, 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()

Illustrative response:

{
  "id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
  "firstName": "Mary",
  "lastName": "Smith",
  "displayName": "Mary Smith",
  "userName": "mary",
  "email": "mary@example.com",
  "role": 0,
  "status": 1,
  "emailConfirmed": true,
  "pictureUrl": "https://cdn.cativalab.digital/avatars/mary.png",
  "coins": 120,
  "badgeId": "01HQ4ABCDEF1234567890XYZ",
  "customer": "makersday",
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "def502004a...",
  "expiresIn": 3600
}

Use the response to:

Confirm the key is valid and points to the right tenant (the customer field).
Capture the id of the user tied to the key (useful for your own logs and audit).
Refresh the session via the returned accessToken / refreshToken.

Admin user CRUD

Partners with an admin API Key manage users directly through the API, under the /admin/users prefix. This is the surface you use to keep the Cativa base in sync with your own system.

Operation	Method and route
List users	`GET /admin/users`
Detail by id	`GET /admin/users/{userId}`
Look up by email	`GET /admin/users/email/{email}`
Create user	`POST /admin/users`
Full update	`PUT /admin/users/{userId}`
Change role	`PUT /admin/users/{userId}/role`
Change status	`PUT /admin/users/{userId}/status`
Change email	`PUT /admin/users/{userId}/email`
Change password	`PUT /admin/users/{userId}/password`
Bind external id	`PATCH /admin/users/{userId}/external-id`
Ban	`POST /admin/users/{userId}/ban`
Delete	`DELETE /admin/users/{userId}`

Create a user

curl -X POST https://apis.cativalab.digital/tenant/api/v2/admin/users \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Mary",
    "lastName": "Smith",
    "email": "mary@example.com",
    "password": "StrongPass#2026",
    "role": 0,
    "phoneNumber": "+15551234567"
  }'

const res = await fetch('https://apis.cativalab.digital/tenant/api/v2/admin/users', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CATIVA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    firstName: 'Mary',
    lastName: 'Smith',
    email: 'mary@example.com',
    password: 'StrongPass#2026',
    role: 0,
    phoneNumber: '+15551234567'
  })
});
const user = await res.json();

Illustrative response (201 Created):

{
  "id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
  "firstName": "Mary",
  "lastName": "Smith",
  "email": "mary@example.com",
  "userName": "mary",
  "displayName": "Mary Smith",
  "role": 0,
  "status": 1,
  "createdAt": "2026-07-10T12:00:00Z",
  "phoneNumber": "+15551234567"
}

password is optional. If omitted, the user comes in through an invite or password-set flow, depending on the tenant’s configuration.

Find a user by email

The most direct path when you have the email from your CRM and don’t have the userId:

curl "https://apis.cativalab.digital/tenant/api/v2/admin/users/email/mary@example.com" \
  -H "Authorization: Bearer cativa_live_..."

const email = encodeURIComponent('mary@example.com');
const res = await fetch(
  `https://apis.cativalab.digital/tenant/api/v2/admin/users/email/${email}`,
  { headers: { Authorization: `Bearer ${process.env.CATIVA_API_KEY}` } }
);
const user = await res.json();

Update single fields

Prefer the single-field routes for focused changes: they are safer than a full PUT (they don’t overwrite other fields by accident).

curl -X PUT https://apis.cativalab.digital/tenant/api/v2/admin/users/01HQ7.../role \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "role": 2 }'

curl -X PUT https://apis.cativalab.digital/tenant/api/v2/admin/users/01HQ7.../status \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": 1 }'

curl -X PUT https://apis.cativalab.digital/tenant/api/v2/admin/users/01HQ7.../email \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "email": "new@example.com" }'

Bind your system’s id (`external-id`)

Store your CRM/ERP identifier on the Cativa user. This lets you correlate records on both sides without relying on the email (which can change).

curl -X PATCH https://apis.cativalab.digital/tenant/api/v2/admin/users/01HQ7.../external-id \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "crm_00123" }'

Ban and delete

# Ban (reversible: status becomes Banned)
curl -X POST https://apis.cativalab.digital/tenant/api/v2/admin/users/01HQ7.../ban \
  -H "Authorization: Bearer cativa_live_..."

# Delete
curl -X DELETE https://apis.cativalab.digital/tenant/api/v2/admin/users/01HQ7... \
  -H "Authorization: Bearer cativa_live_..."

End-to-end: sync a member from your CRM

Look up by email

Call GET /admin/users/email/{email}. If it returns 200, the user already exists: store the id and skip to step 3.

Create if missing

If the lookup returns 404, call POST /admin/users with the CRM data. Store the id from the response.

Bind the external id

Call PATCH /admin/users/{userId}/external-id with your system’s identifier. From here on both sides are correlated.

Grant access with a badge

Assign the badge that unlocks the right group/course. See Badges as Permissions.

The applied step-by-step is in Sync members from your CRM.

Self-service user endpoints

Beyond the admin CRUD, the authenticated user manages their own profile:

GET /users/profile/{userName}. A user’s public profile by handle.
PUT /users/profile. Update your own profile.
GET /users/search?query=.... Search users by name (respects the admin system-user filter).

curl https://apis.cativalab.digital/tenant/api/v2/users/profile/mary \
  -H "Authorization: Bearer cativa_live_..."

curl "https://apis.cativalab.digital/tenant/api/v2/users/search?query=mary" \
  -H "Authorization: Bearer cativa_live_..."

Public profile (illustrative):

{
  "id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
  "displayName": "Mary Smith",
  "role": 0,
  "status": 1,
  "profile": {
    "pictureUrl": "https://cdn.cativalab.digital/avatars/mary.png",
    "job": "Product Designer",
    "city": "New York",
    "state": "NY",
    "badgeId": "01HQ4ABCDEF1234567890XYZ"
  },
  "isFollowing": false,
  "followersCount": 42,
  "followingCount": 17,
  "badges": ["01HQ4ABCDEF1234567890XYZ"]
}

Common errors

404 Not Found on email lookup

The user does not exist in that tenant. This is the expected signal to create via POST /admin/users.

409 Conflict on create

A user with that email already exists in the tenant. Look up by email before creating (the standard sync flow).

403 Forbidden on /admin routes

The key lacks admin scope. /admin/users routes require an admin API Key. Ask the tenant admin for the right credential.

Get Started

Concepts

Guides

Webhooks

Changelog

The User model

Roles (`role`)

Account status (`status`)

Validate credentials and discover the associated user

Admin user CRUD

Create a user

Find a user by email

Update single fields

Bind your system’s id (`external-id`)

Ban and delete

End-to-end: sync a member from your CRM

Self-service user endpoints

Common errors

Next steps

Badges as Permissions

Communities and Spaces

​The User model

​Roles (role)

​Account status (status)

​Validate credentials and discover the associated user

​Admin user CRUD

​Create a user

​Find a user by email

​Update single fields

​Bind your system’s id (external-id)

​Ban and delete

​End-to-end: sync a member from your CRM

​Self-service user endpoints

​Common errors

​Next steps

Badges as Permissions

Communities and Spaces

The User model

Roles (`role`)

Account status (`status`)

Validate credentials and discover the associated user

Admin user CRUD

Create a user

Find a user by email

Update single fields

Bind your system’s id (`external-id`)

Ban and delete

End-to-end: sync a member from your CRM

Self-service user endpoints

Common errors

Next steps