Autenticacao

A API Externa utiliza um modelo de autenticacao em dois passos: primeiro voce troca suas credenciais (API Key + Secret) por tokens JWT, depois utiliza esses tokens em todas as chamadas subsequentes.

Gerando API Key e Secret

1. Acesse o painel Tesselys: Configuracoes → Integracoes → API Externa
2. Clique em Gerar nova chave
3. Copie imediatamente os valores exibidos:

Campo	Formato	Exemplo
API Key	tesselys_ak_ + 45 caracteres alfanumericos (58 total)	tesselys_ak_7f3b2c9e8a1d4f6g5h0j...
Secret	String base64url (43 caracteres)	Kx9mP2vLqR8nW4tY6uB3cA1dF5gH7jE0iM...

Importante

A API Key e o Secret sao exibidos apenas uma vez no momento da criacao. Nao e possivel recupera-los depois. Se perder, sera necessario revogar e gerar novas credenciais.

Obtendo Tokens de Acesso

POST /external/v1/auth

Troque suas credenciais por tokens de acesso.

Headers:

Header	Valor	Obrigatorio
Content-Type	application/json	Sim
x-api-key	Sua API Key (tesselys_ak_...)	Sim

Body:

{
  "secret": "Kx9mP2vLqR8nW4tY6uB3cA1dF5gH7jE0iM..."
}

Resposta de sucesso (200):

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIi...",
  "companyToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb21wYW55SWQiOiJhYmMxMjM...",
  "expiresIn": 3600
}

Campo	Descricao
accessToken	JWT de acesso. Validade: 1 hora (3600 segundos).
companyToken	Token que identifica a empresa. Deve ser enviado em todas as chamadas.
expiresIn	Tempo de vida do accessToken em segundos.

Resposta de erro (401):

{
  "statusCode": 401,
  "message": "INVALID_CREDENTIALS",
  "friendlyMessage": "API Key ou Secret invalidos."
}

Usando os Tokens

Todas as chamadas autenticadas devem incluir dois headers:

Authorization: Bearer {accessToken}
x-company-token: {companyToken}

Exemplo completo:

curl -X GET https://api.tesselys.com.br/external/v1/persons \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "x-company-token: eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json"

Renovando o Token

Quando o accessToken expirar, voce pode renova-lo sem precisar enviar o Secret novamente.

POST /external/v1/auth/refresh-token

Headers:

Header	Valor	Obrigatorio
Authorization	Bearer {accessToken_expirado}	Sim
x-company-token	Token da empresa	Sim

Resposta de sucesso (200):

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.novo_token...",
  "companyToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.mesmo_company...",
  "expiresIn": 3600
}

Dica

Implemente a renovacao automatica no seu client HTTP. Ao receber um 401, chame o endpoint de refresh e repita a requisicao original com o novo token.

Revogando e Regenerando Chaves

Para revogar uma API Key existente:

1. Acesse Configuracoes → Integracoes → API Externa
2. Localize a chave ativa e clique em Revogar
3. Confirme a acao

Apos revogar, todos os tokens emitidos com aquela chave serao invalidados imediatamente. Para gerar novas credenciais, repita o processo de criacao.

Limite

Cada empresa pode ter no maximo 3 API Keys ativas simultaneamente. Revogue chaves nao utilizadas antes de criar novas.

Boas Praticas de Seguranca

• Nunca exponha a API Key ou Secret em codigo frontend ou repositorios publicos
• Armazene credenciais em variaveis de ambiente ou cofre de segredos (Vault, AWS Secrets Manager, etc.)
• Utilize chaves diferentes para ambientes de desenvolvimento e producao
• Rotacione as chaves periodicamente (recomendado: a cada 90 dias)
• Monitore o uso via painel administrativo para detectar acessos suspeitos