> ## 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 como permissão

> Na Cativa, badges não são gamification. São credenciais que controlam acesso.

<Warning>
  Esse é um conceito **crucial e contra-intuitivo**. Em outras plataformas, badges são recompensas visuais (gamification). **Na Cativa, badges são credenciais de permissão** — eles controlam o que cada usuário pode acessar.
</Warning>

## O modelo

```
Badge "Premium"  ──controla acesso a──>  Grupo "VIP Members"
                 ──controla acesso a──>  Curso "Mentoria 2026"
                 ──controla acesso a──>  Espaço "Lives Exclusivas"

Badge "Mentor"   ──controla acesso a──>  Grupo "Mentores"
                 ──permite─────────────>  Editar conteúdo do grupo
```

Quando um usuário recebe um badge, ele **automaticamente ganha acesso** a tudo o que está atrelado a esse badge na configuração de acesso do grupo. Quando o badge é removido, o acesso some.

## Casos de uso reais

<CardGroup cols={2}>
  <Card title="Compra externa libera grupo" icon="cart-shopping">
    Cliente compra na Hotmart → webhook → sua API recebe → você atribui o badge `Premium` ao usuário → ele já consegue entrar no grupo VIP.
  </Card>

  <Card title="Assinatura cancelada revoga acesso" icon="ban">
    Cancelamento no Stripe → webhook → você remove o badge `Premium` → acesso ao curso some imediatamente.
  </Card>
</CardGroup>

## Como atribuir e remover badges via API

<Note>
  O endpoint público para atribuir/remover badges via API Key será publicado em breve nesta documentação. Por enquanto, atribuição e remoção podem ser feitas no painel admin do tenant ou alinhadas com o time da Cativa via [dev@cativa.digital](mailto:dev@cativa.digital).
</Note>

## Idempotência

Atribuir o mesmo badge duas vezes é idempotente — o estado final é o mesmo. Mesmo comportamento para remoção de um badge que já não existe. Isso simplifica retries em jobs e webhook handlers.

## Diferença para Roles

| Conceito  | O que é                                                    | Exemplo                              |
| --------- | ---------------------------------------------------------- | ------------------------------------ |
| **Badge** | Credencial atribuída ao usuário que abre acesso a recursos | `Premium`, `Mentor`, `Aluno-2026`    |
| **Role**  | Permissão funcional dentro de um recurso específico        | `GroupAdmin`, `Moderator` no Grupo X |

Badge pergunta "você **pode entrar** aqui?". Role pergunta "você **pode editar** o que está aqui?".

## Antipattern: não use badges como tag

<Warning>
  Não crie badges só pra "categorizar" usuários sem que isso libere acesso a algum recurso. Badges que não estão configurados como requisito de acesso em nenhum grupo, espaço ou curso não têm efeito prático e poluem o admin.
</Warning>