Service accounts: tokens de integração

Um service account é a identidade de máquina da sua empresa no Sentrya: um token svc_… que deixa o n8n, um script ou qualquer automação consultar e operar incidentes sem usar o login de uma pessoa. Esta página é para o Admin que vai criar e cuidar desses tokens.

O que é um service account

Os webhooks são a entrada de alertas no Sentrya (token whk_, ver Criar uma fonte de dados). O service account é o par de saída: com ele uma ferramenta externa lê os incidentes da empresa, reconhece (ACK), dispensa alertas de webhook e lista as fontes cadastradas.

O token não pertence a ninguém da equipe. Ele não expira com a sessão de um usuário, não depende de e-mail verificado e continua valendo quando a pessoa que o criou sai da empresa.

Característica	Comportamento
Formato	`svc_` seguido de 64 caracteres hexadecimais (32 bytes aleatórios). Na lista do painel aparece só o prefixo, por exemplo `svc_a1b2c3d4…`.
Armazenamento	O servidor guarda apenas o hash SHA-256. O token completo é exibido uma única vez, na criação.
Papel	Age como Admin: enxerga todos os incidentes da empresa, sem o filtro de Grupos visíveis aplicado a Operador e Visualizador.
Alcance	Só as rotas `/api/v1/svc/*`: ler incidentes, resumo e atividade, ACK, dispensar e listar webhooks. Não cria nem apaga servidores Zabbix, usuários ou fontes.
Empresa	A empresa (org) é resolvida a partir do token no servidor. Nunca é informada no corpo da requisição.
`last_used_at`	Carimbado a cada requisição autenticada (em segundo plano, sem atrasar a resposta). Aparece como Último uso na lista.

O papel é Admin, mas o alcance não. O escopo do token é definido pela seleção de rotas onde ele é aceito, não pelo papel. Mesmo agindo como Admin, um svc_ recebe 401 em qualquer rota fora de /api/v1/svc/*.

Onde criar

Service accounts são geridos apenas no painel /admin, em app.flowbix.com/admin → Integrações. Essa tela não existe no app nem no painel web novo (web.sentrya.flowbix.com).

Na aba Integrações você vê o indicador Tokens ativos e uma tabela com Nome, Token (só o prefixo), Criado, Último uso e Status (ativo, desativado ou revogado).

Criar um token

Abra Integrações e clique em Novo token.
Dê um nome no campo Nome (até 80 caracteres). Use algo que identifique a integração, como "n8n produção".
Confirme com sua senha no campo Sua senha. O painel pede a senha porque um token dá acesso à API da empresa. Senha errada devolve 422 com code: "invalid_password" e nada é criado.
Copie o token agora com Copiar token. Ele não será exibido de novo. Só então clique em Concluir.
Configure a integração com o valor copiado, no header Authorization: Bearer svc_… (ver Autenticação, erros e limites da API).

O token é mostrado uma única vez. Se você fechar o modal sem copiar, não há como recuperá-lo: exclua o registro e crie outro.

Ativar e desativar

Cada linha da tabela tem a ação Desativar (quando o token está ativo) ou Ativar (quando está desativado). Desativar é reversível e não pede senha: o token para de autenticar imediatamente e volta a valer assim que for reativado, sem gerar um valor novo. Enquanto uma integração está desativada, as requisições dela recebem 401 token inválido.

Tokens marcados como revogado vêm de uma versão anterior do painel. A revogação era permanente, então esses registros só aceitam Excluir.

Excluir

Excluir apaga o registro de vez. O painel abre o modal Excluir token, avisa que o token será apagado permanentemente e pede Sua senha de novo. Integrações que usam o token param na hora e não há como desfazer. Se você quer só pausar, use Desativar.

Limite por plano

A quantidade de service accounts é limitada pela chave max_service_accounts do plano da empresa. Só tokens ativos ocupam vaga: desativados e revogados não contam. Ao atingir o teto, a criação é recusada com 403 e este corpo:

{"error": "limite do seu plano atingido", "code": "limit_reached", "limit_key": "max_service_accounts"}

Os valores de cada plano estão em Planos e limites.

Quem pode fazer o quê

Ação	Admin	Operador	Visualizador
Ver a lista (nome, prefixo, datas, status)	Sim	Sim	Sim
Criar (exige senha)	Sim	Não	Não
Ativar / Desativar	Sim	Não	Não
Excluir (exige senha)	Sim	Não	Não

A lista nunca expõe o token nem o hash, só metadados. Detalhes dos papéis em Papéis e permissões.

Quando o token para de valer

Além de desativado, revogado ou excluído, um token deixa de autenticar quando a empresa é suspensa, tem o cadastro recusado ou o período de teste vence. Nesses casos a resposta é 403 organização indisponível em todas as rotas /svc. Uma empresa ainda aguardando aprovação continua conseguindo usar o token.

Boas práticas

Um token por integração. Crie um para o n8n, outro para o script de plantão, outro para o painel de TV. O campo Último uso passa a dizer exatamente qual integração está viva, e desativar um deles não derruba os outros.

Rotacionar = criar novo + excluir o antigo. Não existe "regenerar". Crie o token novo, troque na integração, confirme pelo Último uso que o novo está sendo usado e só então exclua o antigo.
Guarde como segredo. Cofre de credenciais ou variável de ambiente, nunca no código nem em mensagens de chat. Quem tem o token enxerga todos os incidentes da empresa.
Prefira Desativar para pausas. Manutenção, teste ou suspeita de vazamento: desative primeiro, investigue, depois decida entre reativar e excluir.
Nomeie pelo destino. "n8n produção" e "n8n homologação" são melhores do que "token 1" e "token 2".