Identidade e usuários

Toda integração com a Cativa começa pelo usuário. Esta página descreve o modelo User no nível conceitual, o endpoint canônico para validar credenciais e o CRUD administrativo que você usa para criar, atualizar e vincular usuários ao seu CRM ou ERP.

O modelo User

Cada usuário pertence a um único tenant e é identificado por um id (GUID). O mesmo usuário nunca existe em dois tenants: se a mesma pessoa participa de duas comunidades, são dois registros distintos. Os campos mais usados em respostas autenticadas:

Campo	Tipo	O que é
`id`	GUID	Identificador único do usuário no tenant.
`firstName` / `lastName`	string	Nome e sobrenome.
`displayName`	string	Nome exibido na comunidade.
`userName`	string?	Handle público (usado em `GET /users/profile/{userName}`).
`email`	string	Email de login.
`pictureUrl`	string?	URL pública da foto de perfil.
`role`	enum	Papel funcional na comunidade (ver tabela abaixo).
`status`	enum	Estado da conta (ver tabela abaixo).
`badgeId`	GUID?	Badge de destaque (o de maior relevância que alimenta o menu e o CTA).
`coins`	int	Saldo de moedas do usuário.
`customer`	string	Slug do tenant ao qual o usuário pertence.

O contrato detalhado de cada response (nomes e tipos exatos de todos os campos) está publicado na aba API Reference, na tag Users / Auth. Os JSON desta página são ilustrativos.

Papéis (`role`)

Valor	Nome	Descrição
`0`	User	Membro comum.
`1`	Admin	Administrador do tenant.
`2`	ContentManager	Gerencia conteúdo.
`3`	ContentCreator	Cria conteúdo.

Status da conta (`status`)

Valor	Nome	Descrição
`0`	Inactive	Conta inativa.
`1`	Active	Conta ativa.
`2`	IncompleteRegister	Cadastro incompleto.
`3`	PendingConfirmation	Aguardando confirmação de email.
`4`	Banned	Banido.
`5`	ForcePasswordChange	Precisa trocar a senha no próximo login.
`6`	Expired	Acesso expirado.

Existe em toda comunidade um usuário de sistema com userName = "admin" (interno da plataforma). Ele nunca aparece em listagens, buscas ou seletores. Ignore-o caso apareça em algum export.

Validar credencial e descobrir o usuário associado

O endpoint canônico para parceiros validarem uma credencial e descobrirem o usuário associado é GET /auth/me. Use-o no boot da sua integração e sempre que precisar confirmar o contexto.

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

Resposta ilustrativa:

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

Use o retorno para:

Confirmar que a chave é válida e aponta pro tenant certo (campo customer).
Capturar o id do usuário associado à chave (útil pra logs e auditoria do seu lado).
Renovar a sessão com os campos accessToken / refreshToken retornados.

CRUD administrativo de usuários

Parceiros com API Key administrativa gerenciam usuários direto pela API, sob o prefixo /admin/users. Esta é a superfície que você usa para manter a base da Cativa em sincronia com o seu sistema.

Operação	Método e rota
Listar usuários	`GET /admin/users`
Detalhe por id	`GET /admin/users/{userId}`
Lookup por email	`GET /admin/users/email/{email}`
Criar usuário	`POST /admin/users`
Atualização completa	`PUT /admin/users/{userId}`
Trocar papel	`PUT /admin/users/{userId}/role`
Trocar status	`PUT /admin/users/{userId}/status`
Trocar email	`PUT /admin/users/{userId}/email`
Trocar senha	`PUT /admin/users/{userId}/password`
Vincular id externo	`PATCH /admin/users/{userId}/external-id`
Banir	`POST /admin/users/{userId}/ban`
Excluir	`DELETE /admin/users/{userId}`

Criar um usuário

curl -X POST https://apis.cativalab.digital/tenant/api/v2/admin/users \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Maria",
    "lastName": "Silva",
    "email": "maria@exemplo.com",
    "password": "SenhaForte#2026",
    "role": 0,
    "phoneNumber": "+5511999998888"
  }'

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: 'Maria',
    lastName: 'Silva',
    email: 'maria@exemplo.com',
    password: 'SenhaForte#2026',
    role: 0,
    phoneNumber: '+5511999998888'
  })
});
const user = await res.json();

Resposta ilustrativa (201 Created):

{
  "id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
  "firstName": "Maria",
  "lastName": "Silva",
  "email": "maria@exemplo.com",
  "userName": "maria",
  "displayName": "Maria Silva",
  "role": 0,
  "status": 1,
  "createdAt": "2026-07-10T12:00:00Z",
  "phoneNumber": "+5511999998888"
}

password é opcional. Se omitido, o usuário entra por convite ou fluxo de definição de senha, dependendo da configuração do tenant.

Achar um usuário pelo email

O caminho mais direto quando você tem o email vindo do seu CRM, sem precisar do userId:

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

const email = encodeURIComponent('maria@exemplo.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();

Atualizar campos pontuais

Prefira as rotas de campo único para mudanças focadas: elas são mais seguras que um PUT completo (não sobrescrevem outros campos por acidente).

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

Vincular o id do seu sistema (`external-id`)

Guarde o identificador do seu CRM/ERP no usuário Cativa. Isso permite correlacionar registros nos dois lados sem depender do email (que pode mudar).

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

Banir e excluir

# Banir (reversível: status vira Banned)
curl -X POST https://apis.cativalab.digital/tenant/api/v2/admin/users/01HQ7.../ban \
  -H "Authorization: Bearer cativa_live_..."

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

Fluxo ponta a ponta: sincronizar um membro do CRM

Procure pelo email

Chame GET /admin/users/email/{email}. Se retornar 200, o usuário já existe: guarde o id e pule para o passo 3.

Crie se não existir

Se o lookup retornar 404, chame POST /admin/users com os dados do CRM. Guarde o id da resposta.

Vincule o id externo

Chame PATCH /admin/users/{userId}/external-id com o identificador do seu sistema. A partir daqui os dois lados ficam correlacionados.

Libere acesso com badge

Atribua o badge que dá acesso ao grupo/curso certo. Veja Badges como permissão.

O passo a passo aplicado está em Sincronizar membros do CRM.

Endpoints do próprio usuário (self-service)

Além do CRUD admin, o usuário autenticado gerencia o próprio perfil:

GET /users/profile/{userName}. Perfil público de um usuário pelo handle.
PUT /users/profile. Atualiza o próprio perfil.
GET /users/search?query=.... Busca usuários por nome (respeita o filtro do usuário de sistema admin).

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

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

Perfil público (ilustrativo):

{
  "id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
  "displayName": "Maria Silva",
  "role": 0,
  "status": 1,
  "profile": {
    "pictureUrl": "https://cdn.cativalab.digital/avatars/maria.png",
    "job": "Product Designer",
    "city": "São Paulo",
    "state": "SP",
    "badgeId": "01HQ4ABCDEF1234567890XYZ"
  },
  "isFollowing": false,
  "followersCount": 42,
  "followingCount": 17,
  "badges": ["01HQ4ABCDEF1234567890XYZ"]
}

Erros comuns

404 Not Found no lookup por email

O usuário não existe naquele tenant. É o sinal esperado para criar via POST /admin/users.

409 Conflict ao criar

Já existe um usuário com aquele email no tenant. Use o lookup por email antes de criar (padrão do fluxo de sincronização).

403 Forbidden nas rotas /admin

A chave não tem escopo administrativo. Rotas /admin/users exigem API Key administrativa. Peça a credencial certa ao admin do tenant.

Comece aqui

Conceitos

Guias

Webhooks

Changelog

O modelo User

Papéis (`role`)

Status da conta (`status`)

Validar credencial e descobrir o usuário associado

CRUD administrativo de usuários

Criar um usuário

Achar um usuário pelo email

Atualizar campos pontuais

Vincular o id do seu sistema (`external-id`)

Banir e excluir

Fluxo ponta a ponta: sincronizar um membro do CRM

Endpoints do próprio usuário (self-service)

Erros comuns

Próximos passos

Badges como permissão

Comunidades e Espaços

​O modelo User

​Papéis (role)

​Status da conta (status)

​Validar credencial e descobrir o usuário associado

​CRUD administrativo de usuários

​Criar um usuário

​Achar um usuário pelo email

​Atualizar campos pontuais

​Vincular o id do seu sistema (external-id)

​Banir e excluir

​Fluxo ponta a ponta: sincronizar um membro do CRM

​Endpoints do próprio usuário (self-service)

​Erros comuns

​Próximos passos

Badges como permissão

Comunidades e Espaços

O modelo User

Papéis (`role`)

Status da conta (`status`)

Validar credencial e descobrir o usuário associado

CRUD administrativo de usuários

Criar um usuário

Achar um usuário pelo email

Atualizar campos pontuais

Vincular o id do seu sistema (`external-id`)

Banir e excluir

Fluxo ponta a ponta: sincronizar um membro do CRM

Endpoints do próprio usuário (self-service)

Erros comuns

Próximos passos