Autenticação

O TapSign oferece dois métodos de autenticação na API: chave de API (token estático, recomendado para integração entre servidores) e JWT (token de acesso com validade curta, obtido com e-mail e senha). Os dois vão no mesmo header:

Authorization: Bearer {token}

Planos com acesso à API

Criar chave de API e emitir token JWT pela API exige um plano com acesso à API: Equipe ou Enterprise. Sem esse acesso, essas rotas respondem 402 com o título Plan Required. Compare os planos em Planos e preços.

Chave de API (recomendado)

A forma mais simples de autenticar. A chave não expira: ela vale até ser desativada ou excluída.

Gerando uma chave pelo painel

1. Entre em tapsign.com.br e abra Integrações
2. Na aba API Keys, clique em Nova API Key
3. Dê um nome que identifique o sistema que vai usar a chave e clique em Criar
4. Copie a chave exibida

A chave aparece uma única vez

O TapSign guarda apenas um hash da chave e não consegue mostrá-la de novo. Armazene em local seguro (variável de ambiente, cofre de segredos). Nunca exponha a chave em código-fonte, repositórios públicos, aplicativos ou no navegador. Se perder, gere uma nova.

Formato da chave

A chave começa com tsk_, seguido de 43 caracteres aleatórios (letras, números, - e _). O mesmo prefixo vale para produção e sandbox.

tsk_3q2Kx9...

Usando a chave

Envie a chave no header Authorization de cada requisição:

curl -X GET "https://api.tapsign.com.br/v1/envelopes?size=1" \
  -H "Authorization: Bearer {token}"

Gerenciamento de chaves

Método	Endpoint	Descrição
POST	/v1/api-keys	Cria uma chave. Body: { "name": "..." }
GET	/v1/api-keys	Lista as chaves do usuário, ativas e desativadas
PATCH	/v1/api-keys/{id}/deactivate	Desativa a chave sem apagar o registro
DELETE	/v1/api-keys/{id}	Exclui a chave (204, sem corpo)

Chaves desativadas ou excluídas passam a receber 401.

Criar chave pela API

A primeira chave precisa de um login: autentique com um token JWT e chame:

curl -X POST https://api.tapsign.com.br/v1/api-keys \
  -H "Authorization: Bearer {access_jwt}" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ERP produção" }'

Resposta (201 Created):

{
  "id": 12,
  "name": "ERP produção",
  "keyPrefix": "tsk_3q2K",
  "rawKey": "tsk_3q2Kx9..."
}

O rawKey só aparece nesta resposta. A listagem mostra apenas o keyPrefix, junto com active, lastUsedAt e createdAt:

[
  {
    "id": 12,
    "name": "ERP produção",
    "keyPrefix": "tsk_3q2K",
    "active": true,
    "lastUsedAt": "2026-09-12T14:32:00Z",
    "createdAt": "2026-09-01T09:00:00Z"
  }
]

Permissões

A chave autentica como o usuário que a criou e tem o mesmo acesso que ele: os mesmos envelopes, modelos, webhooks e organizações. Não existe escopo por chave. Para separar acessos, crie as chaves com usuários diferentes.

---

JWT (token dinâmico)

Alternativa para quem prefere autenticar com e-mail e senha de um usuário. O token de acesso expira, então a integração precisa renovar ou autenticar de novo.

Uma sessão por usuário

O TapSign mantém uma única sessão ativa por usuário. Emitir um token nesta rota encerra as sessões desse usuário no painel, no aplicativo e os tokens emitidos antes. Da mesma forma, um novo login do usuário no painel encerra o token emitido pela API, que passa a receber 401 com SESSION_REVOKED. Em integrações, use a chave de API, que não é afetada por login.

Obter token de acesso

curl -X POST https://api.tapsign.com.br/v1/auth/api/token \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "sua_senha"
  }'

Campo	Tipo	Obrigatório	Descrição
email	string	Sim	E-mail da conta. Até 254 caracteres
password	string	Sim	Senha da conta. Entre 8 e 72 caracteres

Resposta (200 OK):

{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh": "Xk2p9...",
  "expiresIn": 3600
}

Campo	Descrição
access	Token de acesso. Envie como Authorization: Bearer <access>
refresh	Token para renovar o acesso
expiresIn	Validade do access, em segundos

Usando o token JWT

curl -X GET https://api.tapsign.com.br/v1/envelopes \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Atualizar token de acesso

curl -X POST https://api.tapsign.com.br/v1/auth/api/token-refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh": "Xk2p9..."
  }'

Resposta (200 OK):

{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600
}

O refresh token vale para uma única renovação

A renovação invalida o refresh usado e a resposta não traz um novo. Reusar o mesmo refresh alguns segundos depois é tratado como possível roubo de token: a API responde 401 e encerra a sessão. Quando precisar de um novo access, autentique de novo em /v1/auth/api/token. Para integração entre servidores, a chave de API evita esse ciclo.

Validade dos tokens

Token	Validade
Access	1 hora (confira expiresIn)
Refresh	10 dias, para uma única renovação

As rotas de token também têm rate limit próprio por IP: 5 requisições por minuto em /v1/auth/api/token e 10 por minuto em /v1/auth/api/token-refresh.

---

Boas práticas de segurança

1. Nunca exponha credenciais no frontend ou em aplicativos. Chame a API a partir do seu servidor
2. Guarde a chave em variável de ambiente ou cofre de segredos
3. Use uma chave por sistema, com nome claro, para revogar uma sem afetar as outras
4. Rotacione as chaves: crie a nova, atualize o sistema e depois desative a antiga
5. Acompanhe o uso: a listagem de chaves mostra lastUsedAt de cada uma
6. Use HTTPS sempre

Ambientes

Ambiente	Base URL da API	Painel
Produção	https://api.tapsign.com.br	tapsign.com.br
Sandbox	https://sandbox-api.tapsign.com.br	sandbox.tapsign.com.br

Sandbox

As chaves têm o mesmo prefixo tsk_ nos dois ambientes, mas o sandbox tem banco de dados próprio: conta, chaves e webhooks de produção não existem lá, e vice-versa. Veja mais em Ambiente de Testes.