Token de Acesso à API

O Token de Acesso à API é um identificador exclusivo atribuído a um projeto específico ou a vários projetos em sua conta. Ele autentica sua conta para gerenciar seus projetos via API, incluindo modificações na conta, envio de mensagens, edição de projetos, etc.

Tipos de token de Acesso à API

O Pushwoosh oferece dois tipos diferentes de Token de Acesso à API: Servidor e Dispositivo.

Cada tipo de token é válido apenas para seu escopo de API específico. Ocorrerá um erro de autenticação se o token incorreto for usado.

Token de API do Servidor

O token de API do Servidor é usado com todos os métodos da API, exceto aqueles da API do Dispositivo. Ele deve ser incluído no corpo da solicitação no campo auth.

Token de API do Dispositivo

O token de API do Dispositivo é usado exclusivamente com os métodos da API do Dispositivo. Ele deve ser incluído nos cabeçalhos da solicitação HTTP usando o cabeçalho Authorization. Abaixo está um exemplo do formato correto do cabeçalho:

Authorization: Token <device_api_token>

Substitua <device_api_token> pelo valor real do seu Token de API do Dispositivo.

Métodos que exigem um token de API do Dispositivo

Os seguintes métodos da API exigem um token de API do Dispositivo para autorização:

• registerDevice
• unregisterDevice
• deleteDevice
• setTags
• getTags
• setBadge
• applicationOpen
• pushStat
• messageDeliveryEvent
• registerUser
• deleteUser
• postEvent
• registerEmail
• deleteEmail
• setEmailTags
• registerEmailUser
• getInboxMessages
• inboxStatus

Criar e gerenciar tokens de Acesso à API

Você pode visualizar, criar e gerenciar seus tokens de Acesso à API na seção Acesso à API do Painel de Controle da Pushwoosh. Para acessá-la, vá para Configurações → Acesso à API.

Por padrão, cada conta inclui um token chamado Pushwoosh Demo App, que é configurado como um token de servidor.

Criar um novo token de Acesso à API

Para criar um novo token de Acesso à API:

1. Vá para a seção Acesso à API no Painel de Controle.

2. Clique em Gerar Novo Token.

3. Na janela que aparece, escolha o tipo de token:

   • Servidor usado para a maioria dos métodos da API (excluindo os métodos da API do Dispositivo).

   • Dispositivo usado apenas para os métodos da API do Dispositivo.

4. Insira um nome para o token.

5. Clique em Gerar para criar o token.

Importante: Certifique-se de dar ao token acesso ao aplicativo correto no seu Painel de Controle da Pushwoosh. Saiba mais

O novo token aparecerá na lista de Acesso à API. A partir daí, você pode copiar seu valor para uso em solicitações de API ou gerenciar suas permissões de acesso conforme necessário.

Gerenciar um token

Para gerenciar um token de API existente, clique no menu de três pontos (⋮) ao lado da entrada do token na seção Acesso à API.

As seguintes opções estão disponíveis:

Conceder acesso a todos os projetos

Dá ao token acesso a todos os projetos em sua conta. Isso permite que ele use totalmente a API em todos os projetos.

Dica

Dê acesso total apenas aos tokens que precisam. Isso ajuda a manter seus dados seguros e o acesso controlado.

Revogar o acesso de todos os projetos

Remove o acesso do token a todos os projetos em sua conta. O token não poderá mais usar a API até que o acesso seja concedido novamente.

Editar token

Abre a tela Editar Permissões do Token de API, onde você pode:

• Alterar o nome do token

• Copiar o valor do token

• Escolher a quais projetos o token pode acessar, selecionando-os ou desmarcando-os na lista

• Ativar ou desativar as permissões do token: Modificação da conta, Modificação de aplicativos, Modificação de tags, Envio e exclusão de mensagens

• Definir os endereços IP permitidos de onde o token pode ser usado (apenas tokens de Servidor)

A aba Permissões também mostra a última vez que o token foi usado e quantas de suas chamadas foram recusadas nos últimos 7 e 30 dias.

Depois de terminar de fazer as alterações, clique em Salvar para aplicá-las.

Dica

Dê aos tokens acesso apenas aos projetos de que eles precisam. Isso ajuda a proteger sua conta и controlar o que cada token pode fazer.

Verificar o diário de uso de um token

Abra a aba Diário de uso na tela Editar Permissões do Token de API para revisar cada chamada de API feita com o token nos últimos 90 dias. Escolha um resultado (Qualquer resultado, Aceito, Concluído, Recusado: endereço IP, Recusado: sem direitos) e um intervalo de datas, depois clique em Aplicar para filtrar a lista. Clique em Exportar CSV para baixar o registro filtrado como um arquivo CSV.

Excluir token

Remove permanentemente o token da sua conta.

Cuidado

Esta ação não pode ser desfeita. Uma vez excluído, o token não pode ser recuperado. Certifique-se de que o token não está mais em uso antes de excluí-lo.

Autorizando solicitações de API

Para autorizar solicitações de API, use o tipo correto de token de Acesso à API com base no tipo de método de API que você está chamando:

Para métodos da API do Servidor

Inclua o token no campo “auth” do corpo da solicitação:

Exemplo:

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "yxoPUlwqm…………pIyEX4H", // cole seu token de servidor aqui
    "notifications": [{
      "send_date": "now",
      "content": "Hello world"
    }]
  }
}

Para métodos da API do Dispositivo

Use o token de Dispositivo. Inclua-o no cabeçalho da solicitação HTTP usando o seguinte formato:

Authorization: Token <device_api_token>

Substitua <device_api_token> pelo valor real do seu token.

Cuidado

Certifique-se de que o tipo de token corresponde ao método da API que você está usando. Se o token não corresponder ao tipo exigido, a solicitação retornará um erro de autenticação.

Restringir um token a endereços IP específicos

Um token de Servidor pode ser restrito a uma lista de endereços IP de origem permitidos. Quando a lista é definida, o Pushwoosh só aceita solicitações de API feitas com esse token de um endereço correspondente. Os tokens de Dispositivo não têm essa opção.

Abra Editar token para um token de Servidor e insira os endereços em Endereços IP permitidos:

• Adicione até 50 entradas, IPv4 ou IPv6, cada uma sendo um único endereço (203.0.113.7) ou um intervalo CIDR (203.0.113.0/24).
• Um único endereço é armazenado como um intervalo de comprimento total, por exemplo, 203.0.113.7 se torna 203.0.113.7/32.
• Um intervalo é canonizado para seu endereço de rede, por exemplo, 203.0.113.7/24 se torna 203.0.113.0/24.
• 0.0.0.0/0 e ::/0 são rejeitados, pois corresponderiam a todos os endereços e não forneceriam restrição.
• Deixe a lista vazia para manter o token utilizável de qualquer endereço. Este é o padrão para tokens existentes e novos.

Clique em Salvar para aplicar a lista. O salvamento é rejeitado se a lista tiver mais de 50 entradas ou uma entrada que não seja um endereço válido ou um intervalo CIDR.

O que acontece quando uma solicitação vem de um endereço não permitido

O Pushwoosh verifica os endereços IP permitidos em cada chamada de API feita com o token, seja uma chamada REST v1 (conforme documentado nesta referência de API, por exemplo, a API de Mensagens), uma chamada da API de Mensagens v2 ou uma chamada da API de Customer Journey. Uma solicitação de um endereço fora da lista permitida do token é rejeitada.

O formato da resposta difere dependendo das chamadas que você faz:

• Enviar, cancelar e excluir mensagens, como createMessage, os métodos create*Message específicos do canal, cancelMessage e deleteMessage, retornam HTTP 200 com "status_code": 403 no corpo da resposta, o mesmo que suas outras falhas de autorização.
• Outras chamadas REST v1, como as APIs de Aplicativos, Tags, Geozones, Segmentação (Filtros), Campanhas, Presets, Dispositivos de teste e Estatísticas, retornam um HTTP 403 real com um corpo de erro JSON.
• A API de Mensagens v2 e a API de Customer Journey retornam HTTP 403 com um erro PermissionDenied.

As alterações na lista de permissões levam até 10 minutos para serem aplicadas em todos os lugares

O Pushwoosh armazena em cache a validação do token por 10 minutos, e a invalidação do cache é executada por data center. Restringir ou remover endereços permitidos entra em vigor imediatamente no data center onde a alteração foi feita e em até 10 minutos nos outros.