Tokens de API

O que é um token de API

Um token de API (APPLICATION_TOKEN) é a chave secreta que a sua aplicação utiliza para se autenticar na API do BulkGate. Juntamente com o Application ID (APPLICATION_ID) forma o conjunto completo de dados de acesso — sem ambos, a API rejeita o pedido.

O token é uma cadeia aleatória de 50 caracteres composta por algarismos e letras minúsculas e maiúsculas. É guardado de forma encriptada e não expira — mantém-se válido até ser regenerado, desativado ou eliminado por si.

Um token é criado automaticamente no momento em que cria a API. Pode adicionar mais a qualquer momento — por exemplo, um por servidor ou por ambiente, para que seja possível revogar um sem afetar os restantes.

Onde encontrar o token

1. Clique em Módulos e APIs no menu do portal
2. Clique no cartão da sua aplicação em Minhas APIs e módulos
3. Permaneça no separador Definições e encontre a secção Credenciais de login

Esta secção contém o Application ID e, por baixo, no subtítulo Application Token, a lista de tokens dessa aplicação. Um token nunca é apresentado de imediato — vê apenas os seus primeiros e últimos quatro caracteres, o resto é substituído por asteriscos.

O ícone à esquerda indica o estado do token: verde significa ativado, vermelho significa desativado. Um token desativado aparece também riscado.

O botão com o olho riscado à direita de cada token revela-o; as restantes ações estão escondidas atrás do ícone de três pontos Mais ações.

Como revelar e copiar um token

1. Clique no ícone do olho riscado junto ao token que pretende ver
2. Abre-se a caixa de diálogo Mostrar token, que lhe pede que verifique o que o rodeia
3. Introduza a palavra-passe da sua conta e clique em Continuar
4. O token é apresentado por extenso e o ícone muda para Cópia de, que o copia para a área de transferência

Como adicionar outro token

1. Clique em Adicionar token na parte inferior da secção Credenciais de login
2. Introduza a palavra-passe da sua conta
3. Clique em Adicionar

O portal confirma com Token foi criado e apresenta o novo token por extenso — copie-o de imediato, porque depois de recarregar a página fica oculto como os restantes. Não há limite para o número de tokens que uma aplicação pode ter.

Como regenerar um token

A regeneração substitui o token existente por um novo. Mantém o seu lugar na lista, apenas o valor muda.

1. Clique em Mais ações junto ao token e escolha Gere um novo
2. Introduza a palavra-passe da sua conta
3. Clique em Gere um novo

O portal confirma com Token foi regenerado.

Como desativar e reativar um token

Desativar um token é a alternativa reversível à eliminação: o token permanece na lista, mas deixa de poder ser utilizado para autenticação.

1. Clique em Mais ações junto ao token
2. Escolha Desabilitar, ou Habilitar no caso de um token já desativado
3. Confirme na caixa de diálogo que se abre

O portal confirma com O token foi desativado ou O token foi ativado. Esta ação não requer palavra-passe.

Como eliminar um token

1. Clique em Mais ações junto ao token e escolha Excluir
2. Confirme com Excluir na caixa de diálogo Excluir token

O portal confirma com O token foi removido. Também esta ação não requer palavra-passe.

Todos os tokens de uma aplicação desaparecem também no momento em que elimina a própria aplicação.

Como o token é enviado para a API

O Application ID e o token são enviados como parâmetros application_id e application_token — no corpo do pedido ou na query string. A outra opção é assinar um JWT com o token e enviá-lo num cabeçalho.

Um token inválido, desativado ou eliminado resulta numa resposta com o código HTTP 401 e o tipo de erro unknown_identity. Recebe a mesma resposta quando a própria aplicação está desativada ou quando tem endereços IP permitidos configurados e o pedido chega de outro lado. Os restantes erros estão listados na página Tipos de erro da API.

Como utilizar o token num JWT assinado

Em vez de enviar o token em cada pedido, pode assinar um JWT com ele e enviar esse JWT. O token fica assim do seu lado — apenas a assinatura derivada dele circula pela rede.

Coloque o JWT final no cabeçalho Authorization:

Para que a API o aceite, o JWT tem de ter este aspeto:

O payload para a aplicação número 39238 tem, portanto, este aspeto:

Pode limitar a validade de um JWT individual com o campo expire dentro de application_parameters. O valor é um timestamp Unix em segundos; quando é atingido, o JWT deixa de funcionar:

Sem este campo, o JWT é válido enquanto for válido o token que o assinou. É, por isso, útil sempre que entrega o JWT a terceiros — assina-o com uma validade curta e o próprio token fica consigo.

A assinatura é verificada em relação a todos os tokens ativados da aplicação, pelo que pode assinar o JWT com qualquer um deles. Um token desativado ou eliminado não passa — aplica-se o mesmo que foi descrito acima: uma resposta com o código HTTP 401 e o tipo de erro unknown_identity.