Badges as Permissions

This is a crucial and counter-intuitive concept. In other platforms, badges are visual rewards (gamification). In Cativa, badges are permission credentials: they control what each user can access.

The model and the why

Instead of tying each user to each group individually (which doesn’t scale), Cativa uses an indirection layer: the badge. The user receives a badge, and the badge unlocks everything attached to it. Changing access for a thousand people becomes one badge operation, not a thousand group operations. Think of a badge as an access card. The “Premium” card opens certain doors in the building. You don’t configure door by door for each employee: hand out the right card and the right doors open on their own.

Badge "Premium"  --grants access to-->  Group "VIP Members"
                 --grants access to-->  Course "Mentoring 2026"
                 --grants access to-->  Space "Exclusive Lives"

Badge "Mentor"   --grants access to-->  Group "Mentors"

When a user receives a badge, they automatically gain access to everything that badge unlocks in the group/course access configuration. When the badge is removed, access is revoked immediately.

Badge lifecycle

Create the badge (admin)

A badge is created once, via POST /admin/membership/badges or in the dashboard. It has a name, an image, and a relevance.

Configure access (dashboard)

The admin marks, on each group/course access screen, which badges unlock entry. This binding lives in the dashboard, not in the partner API.

Assign to the user (API)

You assign the badge to the user (by userId or by email). Access is unlocked at that moment.

Remove when needed (API)

Removing the badge revokes access immediately. Ideal for subscription cancellation.

Real-world use cases

External purchase grants access

User buys on Hotmart: the webhook hits your API, you assign the Premium badge, and they enter the VIP group right away.

Cancelled subscription revokes access

Cancellation on Stripe: the webhook arrives, you remove the Premium badge, and course access is gone instantly.

Cohort with an expiry

Student in the 2026 cohort: assign the badge with an expirationDate and access expires on its own at the end.

Mentor role

Promoted someone to mentor: the Mentor badge opens the mentors’ group without touching each group by hand.

The user’s badges

To list the authenticated user’s badges, use GET /membership/badges/my:

curl https://apis.cativalab.digital/tenant/api/v2/membership/badges/my \
  -H "Authorization: Bearer cativa_live_..."

const res = await fetch('https://apis.cativalab.digital/tenant/api/v2/membership/badges/my', {
  headers: { Authorization: `Bearer ${process.env.CATIVA_API_KEY}` }
});
const { badges } = await res.json();

Illustrative response:

{
  "badges": [
    {
      "id": "01HQ9USERBADGE1234567890AB",
      "badgeId": "01HQ4ABCDEF1234567890XYZ",
      "name": "Premium",
      "imageUrl": "https://cdn.cativalab.digital/badges/premium.png",
      "isPublic": true,
      "expirationDate": "2026-12-31T23:59:59Z",
      "createdAt": "2026-07-10T12:00:00Z"
    }
  ]
}

id is the user/badge link (the assignment); badgeId is the badge itself. To revoke, use the badgeId. The JSON here is illustrative: the field-by-field schema lives in the API Reference tab (Badge tag).

Admin badge API

Under the /admin/membership/badges prefix:

Operation	Method and route
Create badge	`POST /admin/membership/badges`
Update badge	`PUT /admin/membership/badges/{id}`
Delete badge	`DELETE /admin/membership/badges/{id}`
List badges	`GET /admin/membership/badges`
Assign by `userId`	`POST /admin/membership/badges/{badgeId}/users/{userId}`
Assign by email	`POST /admin/membership/badges/{badgeId}/users/by-email`
Remove from a user	`DELETE /admin/membership/badges/{badgeId}/users/{userId}`
List badge users	`GET /admin/membership/badges/{badgeId}/users`
Change expiration	`PATCH /admin/membership/badges/{badgeId}/users/{userId}/expiration`

Create a badge

curl -X POST https://apis.cativalab.digital/tenant/api/v2/admin/membership/badges \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium",
    "imageUrl": "https://cdn.cativalab.digital/badges/premium.png",
    "relevance": 100,
    "isPublic": true
  }'

Illustrative response (201 Created):

{ "id": "01HQ4ABCDEF1234567890XYZ", "createdAt": "2026-07-10T12:00:00Z" }

relevance decides which badge becomes the “highlight” one (the profile’s badgeId) when a user has several. The highest-relevance badge drives the menu and the CTA.

Assign a badge

Assign by email when you only have the CRM email and don’t want to resolve the userId first. If you already have the userId, use the direct route.

curl -X POST \
  "https://apis.cativalab.digital/tenant/api/v2/admin/membership/badges/01HQ4.../users/by-email" \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "email": "mary@example.com" }'

curl -X POST \
  "https://apis.cativalab.digital/tenant/api/v2/admin/membership/badges/01HQ4.../users/01HQ7..." \
  -H "Authorization: Bearer cativa_live_..."

const badgeId = '01HQ4ABCDEF1234567890XYZ';
await fetch(
  `https://apis.cativalab.digital/tenant/api/v2/admin/membership/badges/${badgeId}/users/by-email`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.CATIVA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ email: 'mary@example.com' })
  }
);

Both accept an optional expirationDate (ISO 8601). Without it, access does not expire.

{ "email": "mary@example.com", "expirationDate": "2026-12-31T23:59:59Z" }

Remove a badge

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

Access to everything that depended on that badge is gone immediately.

Adjust the expiration

Extend or shorten access without re-assigning:

curl -X PATCH \
  "https://apis.cativalab.digital/tenant/api/v2/admin/membership/badges/01HQ4.../users/01HQ7.../expiration" \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "expirationDate": "2027-06-30T23:59:59Z" }'

Idempotency

Assigning the same badge twice is idempotent: the final state is the same, with no error and no duplicate. Removing a badge the user no longer has is idempotent too. This simplifies retries in jobs and webhook handlers: you can reprocess an event without fear of side effects.

End-to-end: external purchase grants access

Receive the purchase webhook

Your API receives the purchase event from the external provider (Hotmart, Stripe, etc.) with the buyer’s email.

Ensure the user in Cativa

Look up by email (GET /admin/users/email/{email}); if missing, create (POST /admin/users). See Identity and Users.

Assign the badge

POST /admin/membership/badges/{badgeId}/users/by-email with the email. Group/course access opens immediately.

On cancellation, remove the badge

When the cancellation webhook arrives, DELETE the assignment. Access is revoked.

The applied step-by-step is in Grant access via external purchase.

Difference from Roles

Concept	What it is	Example
Badge	Credential assigned to the user that opens access to resources	`Premium`, `Mentor`, `Student-2026`
Role	Functional permission within a specific resource	`GroupAdmin`, `Moderator` on Group X

Badge asks “can you enter here?”. Role asks “can you edit what’s here?”.

Common errors

404 Not Found on assign

The badgeId does not exist in the tenant, or the email/userId matches no user. Confirm the badge (GET /admin/membership/badges) and the user before assigning.

403 Forbidden

The key lacks admin scope. /admin/membership/badges routes require an admin API Key.

Assigned the badge but access didn't open

The badge exists and was assigned, but no group/course is configured to accept it. That binding is done in the dashboard. Confirm with the tenant admin that the badge is an access requirement on some resource.

Anti-pattern: don’t use badges as tags

Don’t create badges just to “categorize” users without that unlocking access to some resource. Badges that aren’t configured as an access requirement on any group, space, or course have no practical effect and clutter the admin. If you only need metadata, use external-id or profile fields, not a badge.

Next steps

Communities and Spaces

How groups and courses consume badges to gate entry.

Webhooks

Receive user_received_badge and other membership events.

Get Started

Concepts

Guides

Webhooks

Changelog

The model and the why

Badge lifecycle

Real-world use cases

External purchase grants access

Cancelled subscription revokes access

Cohort with an expiry

Mentor role

The user’s badges

Admin badge API

Create a badge

Assign a badge

Remove a badge

Adjust the expiration

Idempotency

End-to-end: external purchase grants access

Difference from Roles

Common errors

Anti-pattern: don’t use badges as tags

Next steps

Communities and Spaces

Webhooks

​The model and the why

​Badge lifecycle

​Real-world use cases

External purchase grants access

Cancelled subscription revokes access

Cohort with an expiry

Mentor role

​The user’s badges

​Admin badge API

​Create a badge

​Assign a badge

​Remove a badge

​Adjust the expiration

​Idempotency

​End-to-end: external purchase grants access

​Difference from Roles

​Common errors

​Anti-pattern: don’t use badges as tags

​Next steps

Communities and Spaces

Webhooks

The model and the why

Badge lifecycle

Real-world use cases

The user’s badges

Admin badge API

Create a badge

Assign a badge

Remove a badge

Adjust the expiration

Idempotency

End-to-end: external purchase grants access

Difference from Roles

Common errors

Anti-pattern: don’t use badges as tags

Next steps