Token da API

Cada conta pode manter um token público ativo. A credencial identifica a conta, não um usuário: quem a gerou permanece registrado somente para auditoria. Em cada operação, x-underchat-user-id seleciona o usuário executor cujas permissões, canais e setores serão aplicados.

A credencial possui 256 bits de entropia e um prefixo identificável; o valor não é uma sessão JWT, não muda ao entrar ou sair do painel e continua válido se o usuário que a gerou for desativado ou perder permissões.

Ciclo de vida

Estado	Significado	Efeito nas chamadas
Não configurado	A conta nunca gerou um token ativo.	Toda chamada autenticada falha.
Ativo	A chave pode ser usada enquanto conta e plano forem válidos.	A API valida o executor de cada requisição.
Rotacionado	Um novo valor substituiu o anterior.	O valor anterior deixa de funcionar imediatamente.
Revogado	O token foi desativado pelo painel.	O valor revogado retorna erro de autenticação.

Não existe expiração automática. A Underchat recusa a chave quando ela estiver revogada ou o plano estiver indisponível. Depois de autenticar a conta, a chamada é recusada se o executor informado estiver inativo, excluído, fora da conta ou sem a permissão exigida pela rota.

Gerar pelo painel

1. Acesse Integração no menu administrativo.
2. No card API pública, selecione Gerar token.
3. Revise o usuário registrado como gerador para fins de auditoria.
4. Confirme e copie a credencial.
5. Armazene-a no cofre de segredos da aplicação consumidora.

O card permite revelar e consultar novamente o token ativo. Isso é possível porque o valor é armazenado de forma criptografada; a autenticação, porém, compara apenas o hash da credencial.

Endpoints de administração

Estes endpoints pertencem ao Manager e são consumidos pelo painel autenticado. Eles exigem a sessão administrativa e a permissão integration_generate_key; não aceitam o próprio token público como autenticação.

Método e caminho	Ação
GET /v1/integration/api-token	Consulta o token ativo e seus metadados.
POST /v1/integration/api-token/generate	Gera o primeiro token ou rotaciona o atual.
DELETE /v1/integration/api-token	Revoga imediatamente o token ativo.

Os contratos de resposta informam:

Campo	Tipo	Uso
configured	boolean	Indica se existe token ativo para a conta.
token_id	UUID ou null	Identificador do registro da credencial.
status	string	Situação atual, por exemplo ativo ou revogado.
token	string ou null	Valor descriptografado, retornado somente quando configurado.
token_preview	string ou null	Trecho seguro para reconhecer a chave sem expor o valor inteiro.
actor_user_id	UUID ou null	Usuário que gerou/rotacionou a chave; somente auditoria.
actor_user_name	string ou null	Nome legível do gerador para auditoria no painel.
created_at	date-time ou null	Momento da primeira geração do registro ativo.
updated_at	date-time ou null	Última rotação ou alteração.
last_used_at	date-time ou null	Última autenticação aceita com essa credencial.

Consulte a referência OpenAPI do ambiente para o formato exato dos metadados de auditoria.

Rotacionar sem indisponibilidade

A rotação invalida o valor anterior imediatamente. Faça uma janela coordenada:

1. pause consumidores ou impeça novas tarefas;
2. gere o novo token no card;
3. atualize o secret manager;
4. reinicie ou recarregue os consumidores;
5. valide uma operação de leitura e uma operação de escrita;
6. retome o processamento.

Como só existe um token ativo, não há período de sobreposição entre chaves. Planeje a rotação como uma troca atômica do segredo da aplicação.

Revogar

Use Revogar token quando uma credencial puder ter sido exposta ou quando a integração for descontinuada. Para impedir que uma pessoa atue como executor, desative o usuário ou remova suas permissões; não é necessário rotacionar a chave da conta. A revogação invalida o cache de autenticação sem janela de tolerância.

Poder da credencial

Quem possui a chave pode selecionar qualquer usuário ativo da conta em x-underchat-user-id. O header de executor é um seletor de contexto, não um segundo segredo. Restrinja a chave a serviços confiáveis e monitore o executor registrado em cada operação.

Chaves diferentes, finalidades diferentes

A chave inserida no caminho de /v1/webhook/:keyapi identifica um webhook de entrada e está vinculada a um canal/worker. Ela não autentica /v1/chat, /v1/label-template, /v1/sector ou /v1/user. Da mesma forma, o token público do card API não autentica o webhook.

Práticas recomendadas

• restrinja a leitura do segredo ao serviço que faz as chamadas;
• nunca registre headers completos em logs, traces ou ferramentas de erro;
• não reutilize o token entre contas ou ambientes;
• rotacione ao suspeitar de exposição ou trocar o sistema consumidor;
• monitore last_used_at para detectar credenciais abandonadas;
• prefira chamadas server-to-server; não exponha o token no navegador.