Token de integração

O token de integração é a forma recomendada de um sistema — ERP, BI, uma rotina própria — chamar a API REST. Ele substitui login, senha e renovação de token: vai no cabeçalho de toda chamada e vale até expirar ou ser revogado.

Authorization: Bearer tai_api_…

O token age em nome de quem o criou, com as permissões dessa pessoa no momento de cada chamada — papel, módulos da empresa e perfis de acesso, a mesma conferência do token JWT. Se a pessoa perde um acesso, o token perde junto; se o usuário é desativado, o token para de funcionar.

Cuidado

O token de integração vale só na API REST. Para agentes de IA, use o token pessoal (MCP) — um não é aceito no lugar do outro.

Criar um token

1. Entre na plataforma com o usuário que a integração vai usar — de preferência um usuário de integração dedicado, com um perfil de acesso só com o que a integração precisa.
2. Abra Perfil → Meu Perfil, aba Integrações (API). A aba aparece para quem tem a permissão TOKEN_API (ou é o dono da conta).
3. Clique em Novo token, dê um nome que diga qual sistema vai usá-lo e escolha a validade (30, 90, 180 ou 365 dias).
4. Marque Permitir escrita se o sistema for criar ou alterar registros. Sem a marca, o token só faz GET.
5. Clique em Criar token e copie o valor na hora — ele aparece uma única vez.

Formato

tai_api_<12 caracteres>_<43 caracteres>

São 64 caracteres. A TAI guarda apenas um hash do segredo: um token perdido não pode ser recuperado, só revogado e substituído.

Usar o token

curl https://api.taitecnologia.com/colaborador/page?size=20 \
  -H "Authorization: Bearer $TAI_TOKEN"

Para conferir quem o token é e o que ele alcança, use GET /auth/me: devolve o usuário, os módulos da empresa e as permissões efetivas.

Escopos

Escopo	O que permite
api:read	Só GET. É o padrão. Qualquer outro método responde 403.
api:write	Também criar, alterar e excluir — dentro das permissões de quem criou o token.

O que o token não alcança

Mesmo com escrita, o token responde 403 em rotas de credencial e de identidade da conta — para que um token vazado não consiga criar outro e sobreviver à própria revogação:

• gestão de tokens (/token-api, /mcp/…) e autorizações OAuth;
• senha da documentação (/swagger-acesso);
• /auth/… (troca de senha, troca de empresa, personificação) — exceto GET /auth/me;
• escrita em /user e /user-role;
• conversa com a Tali (/message, /conversation, /tali).

Contas de administração da plataforma não criam token de integração.

Limites

Limite	Valor
Tokens de integração ativos por pessoa	5
Validade padrão / máxima	90 / 365 dias
Chamadas por minuto, por token	300 (acima disso, 429)

Erros

Status	Quando
401	Token inválido, expirado, revogado, ou usuário/empresa desativados
403	Rota fora do alcance do token, escrita com token só de leitura, ou falta de permissão da pessoa
429	Limite de chamadas por minuto do token

Revogar

Na mesma aba, clique em Revogar: o efeito é imediato. O dono da conta também pode revogar o token de qualquer pessoa da empresa. A lista mostra o último uso de cada token — a forma de perceber um token esquecido.

Gerenciar pela API

As mesmas ações existem na API REST, autenticadas com o token JWT da pessoa (um token de integração não gerencia tokens):

Operação	Rota
Criar	POST /token-api com { "nome", "expiraEmDias", "permitirEscrita" }
Listar	GET /token-api
Revogar	DELETE /token-api/{id}