Token JWT (API REST)

A API REST autentica por token JWT de usuário ou por token de integração. Para sistemas, o token de integração é o caminho recomendado: dispensa senha, login e renovação. Esta página cobre o JWT, que é o que a própria plataforma usa. Ele é enviado em toda chamada no cabeçalho:

Authorization: Bearer <token>

Token	Validade	Para que serve
token	24 horas	Autoriza as chamadas
refreshToken	7 dias	Gera um par novo sem pedir a senha de novo

A resposta do login não traz a data de expiração; ela está na claim exp do token. O refreshToken não é um JWT: é um valor opaco, que deve ser guardado e devolvido como veio.

Nota

O token JWT vale para a API REST. O servidor MCP usa outras credenciais — token pessoal ou OAuth 2.1 — e elas, por sua vez, não valem na API REST; lá, a alternativa ao JWT é o token de integração.

Login por senha

POST /auth
Content-Type: application/json

{ "login": "integracao@suaempresa.com.br", "password": "********" }

Resposta 200:

{
  "userId": 812,
  "userName": "Integração ERP",
  "login": "integracao@suaempresa.com.br",
  "token": "eyJhbGciOi…",
  "refreshToken": "q8V2+fL0x/…=",
  "impersonated": false
}

Credencial inválida responde 401.

Login em mais de uma empresa

O mesmo e-mail pode ter conta em várias empresas (comum em escritórios de contabilidade e grupos econômicos). Nesse caso, o login sem empresa responde 409, e a escolha é feita em dois passos:

1. Liste as empresas da credencial:

   POST /auth/tenants
   Content-Type: application/json
   
   { "login": "integracao@suaempresa.com.br", "password": "********" }

   [
     { "tenantId": 31, "nomeEmpresa": "Matriz Ltda" },
     { "tenantId": 58, "nomeEmpresa": "Filial Comércio Ltda" }
   ]

2. Repita o login informando a empresa:

   { "login": "integracao@suaempresa.com.br", "password": "********", "tenantId": 58 }

Login por código enviado por e-mail (OTP)

Para quem não usa senha. O código tem 6 dígitos, vale 10 minutos, aceita 5 tentativas e pode ser pedido de novo depois de 60 segundos.

POST /auth/otp/request
{ "login": "pessoa@suaempresa.com.br" }

A resposta é sempre 200 — ela não revela se o e-mail existe. Em seguida:

POST /auth/otp/verify
{ "login": "pessoa@suaempresa.com.br", "code": "482913" }

A resposta tem o mesmo formato do login por senha. Com conta em mais de uma empresa, use POST /auth/otp/tenants (mesmo corpo) para listar as empresas e repita o verify com tenantId.

Renovar o token

curl -X POST -G https://api.taitecnologia.com/auth/refresh \
  --data-urlencode "refreshToken=$REFRESH_TOKEN"

await fetch(`https://api.taitecnologia.com/auth/refresh?refreshToken=${encodeURIComponent(refreshToken)}`, {
  method: 'POST',
})

O refreshToken vai na query string, não no corpo, e precisa ser codificado — ele contém +, / e =, e sem codificação a chamada responde 401. A resposta traz um par novo. Um refreshToken vencido ou inválido também responde 401: aí é preciso logar de novo.

Quem sou eu

GET /auth/me
Authorization: Bearer <token>

Devolve nome, papéis (roles), módulos contratados pela empresa (modulosHabilitados), o colaborador ligado ao usuário (colaboradorId) e as permissões efetivas. É a forma de conferir, antes de chamar uma rota, se o usuário de integração tem acesso a ela.

Trocar de empresa sem novo login

GET  /auth/my-tenants                    → empresas em que o usuário tem conta ativa
POST /auth/switch-tenant/{tenantId}      → novo par de tokens já na outra empresa

A troca responde 403 se o usuário não tem conta ativa naquela empresa, 404 se a empresa não existe e 429 acima de 10 trocas por minuto.

Boas práticas

• Guarde o token em memória e renove-o com o refreshToken antes das 24 horas, em vez de logar a cada chamada.
• Trate 401 como “renovar ou logar de novo”: {"error": "Expired JWT token"} indica token vencido.
• Use um usuário dedicado à integração, com o mínimo de permissões. A integração aparece com o nome dele no histórico de alterações da plataforma.
• Nunca envie a senha em query string nem a grave em log.