## 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](https://www.bulkgate.com/pt/documentacao/administracao-da-api/administracao-de-apis/) `(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](#como-adicionar-outro-token) mais a qualquer momento — por exemplo, um por servidor ou por ambiente, para que seja possível revogar um sem afetar os restantes. > [!CAUTION] > Nunca partilhe o token nem o envie para um repositório público. Quem tiver o > token e o Application ID pode enviar mensagens a partir da sua conta. Se suspeitar > de uma fuga, [regenere](#como-regenerar-um-token) ou > [elimine](#como-eliminar-um-token) o token. ## 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`. ![A parte Credenciais de login com a lista de tokens](docs:api-tokens/token-list_en) ## 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 ![A caixa de diálogo Mostrar token a pedir a palavra-passe](docs:api-tokens/token-show_en) > [!NOTE] > Um token revelado só permanece visível até a página ser recarregada. Depois disso, > volta a ficar oculto e terá de introduzir novamente a palavra-passe para o ver. ## 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 menu Mais ações com Gere um novo, Desabilitar e Excluir](docs:api-tokens/token-menu_en) O portal confirma com `Token foi regenerado`. > [!WARNING] > O token antigo deixa de funcionar imediatamente. Todas as integrações que o > utilizavam começam a receber erros — coloque o novo token em uso de imediato. ## 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. > [!CAUTION] > A eliminação é definitiva — o token não pode ser restaurado nem voltar a ser > apresentado. Se pretender apenas bloquear o acesso temporariamente, utilize antes a > [desativação do token](#como-desativar-e-reativar-um-token). 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](#como-utilizar-o-token-num-jwt-assinado) 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](https://www.bulkgate.com/pt/documentacao/administracao-da-api/tipos-de-erro-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`: ```http POST /api/1.0/simple/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json Authorization: Bearer ``` Para que a API o aceite, o JWT tem de ter este aspeto: | Parte | Conteúdo | |:--|:--| | Header | `{"alg":"HS256","typ":"JWT"}` — a API não aceita outro algoritmo nem outro tipo | | Payload | `application_id` com o seu [Application ID](https://www.bulkgate.com/pt/documentacao/administracao-da-api/administracao-de-apis/) | | Signature | HMAC-SHA256 do header e do payload, com o token de API como chave | O payload para a aplicação número 39238 tem, portanto, este aspeto: ```json { "application_id": 39238 } ``` > [!NOTE] > Quando envia um JWT, deixa de precisar de `application_id` ou `application_token` > nos parâmetros do pedido — a API obtém a identidade a partir do payload. 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: ```json { "application_id": 39238, "application_parameters": { "expire": 1800000000 } } ``` 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`.