Badges como permissão

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.

O modelo e o porquê

Em vez de amarrar cada usuário a cada grupo individualmente (o que não escala), a Cativa usa uma camada indireta: o badge. O usuário recebe um badge, e o badge libera tudo o que está atrelado a ele. Trocar o acesso de mil pessoas vira uma operação de badge, não mil operações de grupo. Pense no badge como um crachá de acesso. O crachá “Premium” abre certas portas do prédio. Você não configura porta por porta para cada funcionário: dá o crachá certo e as portas certas abrem sozinhas.

Badge "Premium"  --libera acesso a-->  Grupo "VIP Members"
                 --libera acesso a-->  Curso "Mentoria 2026"
                 --libera acesso a-->  Espaço "Lives Exclusivas"

Badge "Mentor"   --libera acesso a-->  Grupo "Mentores"

Quando um usuário recebe um badge, ele automaticamente ganha acesso a tudo o que aquele badge libera na configuração de acesso do grupo/curso. Quando o badge é removido, o acesso some na mesma hora.

Ciclo de vida de um badge

Criar o badge (admin)

Um badge é criado uma vez, via POST /admin/membership/badges ou no painel. Ele tem nome, imagem e relevância.

Configurar o acesso (painel)

O admin marca, na tela de acesso de cada grupo/curso, quais badges liberam a entrada. Essa amarração vive no painel, não na API de parceiro.

Atribuir ao usuário (API)

Você atribui o badge ao usuário (por userId ou por email). Nesse instante o acesso é liberado.

Remover quando necessário (API)

Ao remover o badge, o acesso é revogado imediatamente. Ideal para cancelamento de assinatura.

Casos de uso reais

Compra externa libera grupo

Cliente compra na Hotmart: webhook chega na sua API, você atribui o badge Premium ao usuário e ele já entra no grupo VIP.

Assinatura cancelada revoga acesso

Cancelamento no Stripe: webhook chega, você remove o badge Premium e o acesso ao curso some na hora.

Turma com validade

Aluno da turma 2026: atribua o badge com expirationDate e o acesso expira sozinho no fim do curso.

Papel de mentor

Promoveu alguém a mentor: o badge Mentor abre o grupo dos mentores sem mexer em cada grupo na mão.

Os badges do usuário

Para listar os badges do usuário autenticado, 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();

Resposta ilustrativa:

{
  "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 é o vínculo usuário/badge (a atribuição); badgeId é o badge em si. Para revogar, use o badgeId. Os JSON aqui são ilustrativos: o schema campo a campo fica na aba API Reference (tag Badge).

API administrativa de badges

Sob o prefixo /admin/membership/badges:

Operação	Método e rota
Criar badge	`POST /admin/membership/badges`
Atualizar badge	`PUT /admin/membership/badges/{id}`
Excluir badge	`DELETE /admin/membership/badges/{id}`
Listar badges	`GET /admin/membership/badges`
Atribuir por `userId`	`POST /admin/membership/badges/{badgeId}/users/{userId}`
Atribuir por email	`POST /admin/membership/badges/{badgeId}/users/by-email`
Remover de um usuário	`DELETE /admin/membership/badges/{badgeId}/users/{userId}`
Listar usuários do badge	`GET /admin/membership/badges/{badgeId}/users`
Alterar expiração	`PATCH /admin/membership/badges/{badgeId}/users/{userId}/expiration`

Criar um 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
  }'

Resposta ilustrativa (201 Created):

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

relevance decide qual badge vira o “de destaque” (badgeId do perfil) quando o usuário tem vários. O de maior relevância alimenta o menu e o CTA.

Atribuir um badge

Atribua por email quando você só tem o email do CRM, sem precisar resolver o userId antes. Se já tem o userId, use a rota direta.

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": "maria@exemplo.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: 'maria@exemplo.com' })
  }
);

Ambas aceitam expirationDate opcional (ISO 8601). Sem ela, o acesso não expira.

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

Remover um badge

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

O acesso a tudo que dependia daquele badge some imediatamente.

Ajustar a expiração

Prorrogue ou encurte o acesso sem re-atribuir:

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" }'

Idempotência

Atribuir o mesmo badge duas vezes é idempotente: o estado final é o mesmo, sem erro nem duplicata. Remover um badge que o usuário já não tem também é idempotente. Isso simplifica retries em jobs e handlers de webhook: você pode reprocessar um evento sem medo de efeito colateral.

Fluxo ponta a ponta: compra externa libera acesso

Receba o webhook da compra

Sua API recebe o evento de compra do provedor externo (Hotmart, Stripe etc.) com o email do comprador.

Garanta o usuário na Cativa

Procure por email (GET /admin/users/email/{email}); se não existir, crie (POST /admin/users). Veja Identidade e usuários.

Atribua o badge

POST /admin/membership/badges/{badgeId}/users/by-email com o email. O acesso ao grupo/curso é liberado na hora.

No cancelamento, remova o badge

Ao receber o webhook de cancelamento, faça DELETE na atribuição. O acesso é revogado.

O passo a passo aplicado está em Liberar acesso via compra externa.

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?”.

Erros comuns

404 Not Found ao atribuir

O badgeId não existe no tenant, ou o email/userId não corresponde a nenhum usuário. Confirme o badge (GET /admin/membership/badges) e o usuário antes de atribuir.

403 Forbidden

A chave não tem escopo administrativo. Rotas /admin/membership/badges exigem API Key administrativa.

Atribuí o badge mas o acesso não abriu

O badge existe e foi atribuído, mas nenhum grupo/curso está configurado para aceitá-lo. Essa amarração é feita no painel. Confirme com o admin do tenant que o badge é requisito de acesso em algum recurso.

Antipattern: não use badges como tag

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. Se você só precisa de metadado, use external-id ou campos de perfil, não badge.

Próximos passos

Comunidades e Espaços

Como grupos e cursos consomem badges para controlar entrada.

Webhooks

Receba user_received_badge e outros eventos de membership.

Comece aqui

Conceitos

Guias

Webhooks

Changelog

O modelo e o porquê

Ciclo de vida de um badge

Casos de uso reais

Compra externa libera grupo

Assinatura cancelada revoga acesso

Turma com validade

Papel de mentor

Os badges do usuário

API administrativa de badges

Criar um badge

Atribuir um badge

Remover um badge

Ajustar a expiração

Idempotência

Fluxo ponta a ponta: compra externa libera acesso

Diferença para Roles

Erros comuns

Antipattern: não use badges como tag

Próximos passos

Comunidades e Espaços

Webhooks

​O modelo e o porquê

​Ciclo de vida de um badge

​Casos de uso reais

Compra externa libera grupo

Assinatura cancelada revoga acesso

Turma com validade

Papel de mentor

​Os badges do usuário

​API administrativa de badges

​Criar um badge

​Atribuir um badge

​Remover um badge

​Ajustar a expiração

​Idempotência

​Fluxo ponta a ponta: compra externa libera acesso

​Diferença para Roles

​Erros comuns

​Antipattern: não use badges como tag

​Próximos passos

Comunidades e Espaços

Webhooks

O modelo e o porquê

Ciclo de vida de um badge

Casos de uso reais

Os badges do usuário

API administrativa de badges

Criar um badge

Atribuir um badge

Remover um badge

Ajustar a expiração

Idempotência

Fluxo ponta a ponta: compra externa libera acesso

Diferença para Roles

Erros comuns

Antipattern: não use badges como tag

Próximos passos