> ## 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.

# Badges as Permissions

> In Cativa, badges are not gamification. They are credentials that gate access.

<Warning>
  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.
</Warning>

## The model

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

Badge "Mentor"   ----gates access to---->  Group "Mentors"
                 ----grants---->           Permission to edit group content
```

When a user receives a badge, they **automatically gain access** to anything tied to that badge in the group's access configuration. When the badge is removed, access is revoked.

## Real-world use cases

<CardGroup cols={2}>
  <Card title="External purchase grants access" icon="cart-shopping">
    User buys on Hotmart -> webhook -> your API receives it -> you assign the `Premium` badge to the user -> user can enter the VIP group immediately.
  </Card>

  <Card title="Cancelled subscription revokes access" icon="ban">
    Cancellation on Stripe -> webhook -> you remove the `Premium` badge -> course access is gone instantly.
  </Card>
</CardGroup>

## How to assign and remove badges via API

<Note>
  The public endpoint for assigning/removing badges via API Key is **coming soon** in this documentation. Until then, assignment and removal can be done in the tenant admin panel or coordinated with the Cativa team at [dev@cativa.digital](mailto:dev@cativa.digital).
</Note>

## Idempotency

Assigning the same badge twice is idempotent — the final state is the same. Same behavior for removing a badge that doesn't exist. This simplifies retries in jobs and webhook handlers.

## 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?".

## Anti-pattern: don't use badges as tags

<Warning>
  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.
</Warning>