Criar e usar um token de API

O token de API é a credencial que o seu sistema usa para falar com a API REST do ODSign. Ele funciona como uma senha: quem tem o token consegue criar, enviar e anular envelopes em nome do usuário que o gerou.

Quem pode criar

Somente administradores da conta. O token age em nome de quem o criou e com o perfil dessa pessoa (veja Usuários e permissões).

Dica: Se a integração vai funcionar por muito tempo, crie o token com um usuário administrador dedicado à integração (por exemplo, "Integração ERP"). Assim, a saída de uma pessoa da empresa não interrompe a integração.

Onde encontrar

No menu lateral, abra Configurações › Conta (ou, no menu do seu nome, Configurações da conta). O quadro Tokens da API fica no fim da página.

Passo a passo: criar um token

1. Em Configurações › Conta, vá até Tokens da API.
2. No campo Nome do token, escreva um nome que identifique o uso, como "ERP" ou "Portal do cliente" (até 60 caracteres).
3. Clique em Criar token.
4. O token aparece no aviso Copie seu token agora. Copie o valor completo (ele começa com ods_) e guarde-o no cofre de segredos do seu sistema.

Atenção: O token é exibido uma única vez. Depois que você sair da página, ele não aparece de novo, nem para a equipe do ODSign. Se perder o valor, crie outro token.

Usar o token

Envie o token em todas as chamadas, no cabeçalho Authorization, precedido de Bearer e um espaço:

curl "https://app.odsign.com.br/api/v1/envelopes?per_page=1" \
  -H "Authorization: Bearer ods_SEU_TOKEN_AQUI" \
  -H "Accept: application/json"

Se a resposta for 200 com uma lista em data, o token está funcionando. A partir daí, veja todas as operações em Referência dos endpoints.

Acompanhar os tokens

A lista abaixo do campo mostra cada token pelo nome, com a data de criação e a data e hora do último uso. Um token que nunca foi usado mostra "—" no último uso. Use essa informação para conferir se a integração está ativa e para identificar tokens esquecidos.

Boas práticas de segurança

• Guarde o token em variável de ambiente ou cofre de segredos, nunca no código-fonte, em planilhas ou em mensagens.
• Use o token só no servidor. Não coloque o token em páginas web, aplicativos de celular ou qualquer código que rode no aparelho do cliente.
• Crie um token para cada sistema integrado, com nomes claros. Assim fica fácil saber qual deles está em uso.
• Lembre-se de que o token tem o mesmo alcance do usuário: o de um administrador alcança todos os envelopes da conta.

Veja também Boas práticas de segurança da conta.

Se o token vazar

Ainda não há botão para revogar um token pelo app. Se um token foi exposto, fale com o suporte para invalidá-lo e, enquanto isso, crie um novo token para a sua integração. Bloquear ou excluir o usuário que criou o token, em Configurações › Usuários, também faz todos os tokens dele pararem de funcionar na hora.

Problemas comuns

• A API responde 401 com "Não autenticado.". Confira se o cabeçalho está exatamente como Authorization: Bearer ods_..., sem aspas a mais, quebras de linha ou espaços no meio do token. O erro também aparece quando o usuário dono do token foi bloqueado ou excluído, ou quando a conta está suspensa (veja Conta suspensa ou acesso bloqueado).
• O quadro Tokens da API não aparece. Só administradores da conta acessam Configurações › Conta.
• A API responde 403 ao criar envelopes. O usuário dono do token não pode enviar envelopes (perfil Visualizador, por exemplo) ou o envio não está liberado no plano.
• O token não vê os envelopes dos colegas. O usuário dono do token não é administrador. Tokens de outros perfis só alcançam os envelopes que a própria pessoa enviou.