Autenticação

A API REST do SIP Caller autentica as solicitações com chaves de API. Cada chave de API tem um token secreto, que sua aplicação envia no cabeçalho Authorization de cada solicitação.

Criar uma chave de API

As chaves de API são criadas no Console Web, em Configurações > Chaves de API, por um usuário com a função Administrador. Ao criar a chave, você escolhe:

• Um nome, para identificar a aplicação que a usa.
• Uma data de expiração. Depois dessa data, a chave deixa de funcionar. A expiração não pode ser estendida posteriormente.
• As funções concedidas à chave, que definem o que a aplicação pode fazer. As funções não podem ser alteradas posteriormente.

Quando a chave é criada, o SIP Caller exibe seu token apenas uma vez. Copie-o e guarde-o em um local seguro, como um gerenciador de segredos. O SIP Caller não armazena o token, portanto ele não pode ser recuperado: se você o perder, crie uma nova chave de API.

Consulte Chaves de API para um guia passo a passo.

Autenticar solicitações

Envie o token como um token Bearer no cabeçalho Authorization:

Todas as solicitações devem ser autenticadas. Tenha em mente que:

• Uma chave de API pertence a uma única conta, portanto o ACCOUNT_ID na URL deve ser o da conta em que a chave foi criada.
• As solicitações devem ser feitas por HTTPS.
• O token é um segredo, e concede acesso à sua conta. Não o inclua em código do lado do cliente, como páginas web ou aplicativos móveis, e não o envie para repositórios de código-fonte.

Funções

Cada endpoint exige que a chave de API tenha pelo menos uma das seguintes funções:

Função	Permite
Administrador de Campanhas	Acesso completo a campanhas, números de campanhas, listas negras, listas de contatos e relatórios de campanhas.
Leitor de Campanhas	Acesso somente leitura a campanhas, números de campanhas, listas negras, listas de contatos e relatórios de campanhas.
Administrador de Números de Campanha	Ler, adicionar e excluir os números das campanhas. Pode ser restrita a campanhas específicas.
Provedor de Números de Campanha	Adicionar números a campanhas, sem poder lê-los nem excluí-los. Pode ser restrita a campanhas específicas.

Conceda a cada aplicação apenas as funções de que ela precisa. Por exemplo, um formulário web que envia novos leads para uma campanha só precisa da função Provedor de Números de Campanha, restrita a essa campanha.

Erros de autenticação

Status	Quando
401 Unauthorized	O cabeçalho Authorization está ausente, ou o token está malformado, é inválido ou expirou.
403 Forbidden	O token é válido, mas a chave de API foi excluída, pertence a outra conta, ou não tem uma função que permita a operação.

Consulte Erros para o formato das respostas de erro.

Revogar uma chave de API

Para revogar o acesso de uma aplicação, exclua sua chave de API em Configurações > Chaves de API. As solicitações feitas com o token de uma chave excluída falham imediatamente com 403 Forbidden.

Recomendamos fazer a rotação das chaves periodicamente: crie uma nova chave, atualize sua aplicação para usá-la, e depois exclua a antiga.