Autenticação

Chaves de API (recomendadas para integrações)

Uma chave de API é um token de acesso pessoal vinculado a um membro da sua conta.

Crie uma em Configurações → Plugins → Chaves de API do RolChat. O segredo é exibido uma única vez; depois disso, apenas os dez primeiros caracteres ficam visíveis, e o RolChat armazena apenas um hash SHA-256.
Formato: rcp_ seguido de 32 bytes aleatórios em base64url, cerca de 45 caracteres no total. O prefixo torna a chave reconhecível nos logs e diferente de um token de sessão.
Escopos: escolhidos em um catálogo fixo de capacidades quando a chave é criada. Uma chave nunca pode fazer mais do que o membro que a criou: a cada chamada, as duas condições são verificadas, a capacidade está nos escopos da chave e o membro ainda a possui. Se a função do membro for restringida, a chave é restringida junto.
Validade: as chaves não expiram sozinhas. Revogue uma chave na página de perfil ou com DELETE /api/v1/tokens/:id; a revogação tem efeito imediato. Não há rotação no lugar: revogue e crie uma nova chave.
A criação e a revogação são registradas no log de auditoria.

Envie-a como token bearer - não existe um cabeçalho separado para a chave de API:

curl https://api.rolchat.com/api/v1/contacts?limit=20 \
  -H "Authorization: Bearer rcp_…" \
  -H "X-Account-Id: 7c1d2c6e-…"

As requisições com uma chave de API de plugin são limitadas a 300 por minuto.

Sessões JWT

O app web e os SDKs móveis fazem login com e-mail e senha (ou Google ou Apple) e recebem um par de tokens.

Token	Validade	Observações
Token de acesso	15 minutos	RS256, verificado com o JWKS em `/.well-known/jwks.json`
Token de renovação	30 dias	Rotacionado a cada renovação; reutilizar um token já rotacionado revoga toda a cadeia

Claims: sub (usuário), acc (conta), rl (função) e, para funções por site, sts (sites permitidos).

POST /auth/login, /auth/refresh, /auth/swap-company e /auth/logout são os únicos endpoints do fluxo de autenticação que não devem trazer o cabeçalho X-Account-Id descrito a seguir.

O cabeçalho `X-Account-Id`

Toda requisição autenticada, exceto as quatro acima, precisa informar a conta em nome da qual está agindo:

X-Account-Id: <account uuid>

O servidor verifica se o cabeçalho é igual ao claim acc do token (ou à conta da chave de API). A ausência do cabeçalho gera 400 missing_required_header; uma divergência gera 403 account_context_mismatch. O cabeçalho existe para que um bug no cliente ou um token reutilizado nunca consiga ler silenciosamente os dados de outra conta: a divergência é rejeitada antes de qualquer consulta, e cada linha de log pode ser atribuída a uma conta sem decodificar o token.

Usuários com várias empresas

Uma pessoa pode pertencer a várias empresas. Cada empresa tem seu próprio token (seu próprio claim acc). Para trocar:

POST /api/v1/auth/swap-company
Authorization: Bearer <current access token>

{ "account_id": "<target uuid>" }

O destino precisa ser uma das available_companies de quem chama (retornadas no login); caso contrário, 403 forbidden. A resposta é um novo par de tokens de acesso e de renovação restrito ao destino; o token de renovação antigo é revogado, e um evento de auditoria auth.account.swapped é registrado.

Autenticação multifator

A MFA baseada em TOTP pode ser cadastrada por membro e exigida por conta. Quando está ativada, POST /auth/login retorna um desafio, e a sessão é concluída com POST /auth/mfa/verify. Códigos de backup são emitidos no cadastro.

As rotas de login são limitadas a 10 tentativas por IP por minuto e 5 por e-mail a cada 15 minutos.
Dez tentativas de login malsucedidas bloqueiam o e-mail por 30 minutos; a resposta traz code: account_locked.
O reCAPTCHA pode ser ativado por ação (cadastro, login, redefinição de senha); a configuração pública inicial é servida por GET /api/v1/captcha.