Autenticação nas APIs da Vonage Business Communications

Depois de criou seu aplicativo, e inscreveu-se na API de provisionamento Você está pronto para criar um token de acesso. As APIs da Vonage Business Communications utilizam OAuth para autenticação.

Criação de chaves de autenticação

Faça login no Portal do Desenvolvedor de Comunicações Empresariais usando suas credenciais de desenvolvedor.
Selecionar Applications no menu de navegação superior.
No Applications página, localize seu aplicativo na tabela e clique no aplicativo nome link.
Selecione o Chaves de produção no menu de navegação à esquerda:

Observação: O tipo de concessão padrão é Password. O tipo de subsídio é o método que o OAuth utiliza para gerar um token de acesso. Ao criar um aplicativo de produção, normalmente você vai querer usar Code método para autenticar solicitações. O Refresh Token Essa opção criará um novo token quando o atual expirar.
Se Code selecionado, no URL de retorno de chamada No campo, insira uma URL de retorno válida que seu aplicativo usará para receber o código gerado. Se você ainda não criou seu aplicativo, insira http://localhost Por enquanto, lembre-se de inserir a URL correta quando estiver pronto para testá-la.

Observação: Se você planeja usar o tipo de concessão por senha para seu aplicativo, não será necessário usar uma URL de retorno para recuperar o token, como seria necessário no fluxo de código de autorização. Caso esteja usando a concessão por senha, você pode deixar esse campo em branco.
Clique no Gerar chaves botão. Isso gera o Chave do Consumidor e Segredo do Consumidor que seu aplicativo utilizará para solicitar um token.

Tipos de subsídios aceitos

A Vonage Business Communications oferece suporte aos seguintes tipos de concessão para a geração de tokens de acesso.

Código de autorização - O tipo de concessão “Código de autorização” é utilizado por clientes confidenciais e públicos para trocar um código de autorização por um token de acesso. Depois que o usuário retornar ao cliente por meio da URL de redirecionamento, o aplicativo obterá o código de autorização a partir da URL e o utilizará para solicitar um token de acesso.
Concessão de senha - O tipo de autorização “Senha” é uma forma de trocar as credenciais de um usuário por um token de acesso.

Quando usar o tipo de concessão “Senha”?

O tipo de concessão “Senha” exige que o aplicativo colete a senha do usuário. Recomenda-se que o tipo de concessão “Senha” seja utilizado apenas para habilitar aplicativos servidor a servidor, nos quais não é necessário coletar as credenciais do usuário.

Veja o Exemplos de pontos finais e Geração de tokens de acesso exemplos para aprender como solicitar o código de autenticação e trocá-lo por um token de acesso:

Na produção, você deve usar o código_de_autorização tipo de subsídio (Code) e essa é a única opção exibida na aba “Meus aplicativos” em apimanager.uc.vonage.com. O Code Esse tipo de concessão exige que sua solicitação implemente uma URL de retorno válida para recuperar o código de autorização dos servidores da Vonage e trocá-lo por um token. Consulte os exemplos de Endpoint na guia “Minhas aplicações” para saber como criar as solicitações de autorização e de token.

Autenticação com o método de concessão de código de autorização

Aviso: O SSO não é compatível no momento

O exemplo a seguir mostra como obter um authorization_code por meio do endpoint authorize.

https://api.vonage.com/authorize?scope=openid&response_type=code&redirect_uri=$REDIRECT_URI&client_id=$CONSUMER_KEY

REDIRECT_URI - A URL para a qual o usuário será redirecionado após a autenticação.
CONSUMER_KEY - A chave de consumidor que você gerou na etapa 5 acima

O exemplo a seguir mostra como trocar um código de autorização por um token por meio do endpoint de token

curl --request POST 'https://api.vonage.com/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic $AUTHORIZATION' \ --data-urlencode 'grant_type=authorization_code' \ --data-urlencode 'code=$AUTHORIZATION_CODE' \ --data-urlencode 'redirect_uri=$REDIRECT_URI'

AUTHORIZATION_CODE - O código recebido pelo redirect_uri após o login bem-sucedido.
REDIRECT_URI - A URL para a qual o usuário será redirecionado após a troca do código de autorização.
AUTHORIZATION - Um token codificado em Base64 das credenciais do aplicativo no formato $CONSUMER_KEY:$CONSUMER_SECRET.

Após trocar o token, você receberá uma resposta JSON com o access_token incorporado nele. Você precisa desse token para usar as APIs de Account, Extensão e Usuário:

{
   "access_token":"xyz123eyJ4NQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFemhrWmciLCJraWQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFNemhrWmciLCJhbGciOiJSUzI1NiJ9..gs7JO2RLPFIld7NXM9gnOy9CYaLs_EYXJJilxX76MFBiidoiG9sIW4RkeHLvDVLyFP1eVd_Pt7000wAr13mcXn-6x6D9oJeAH_Iz8nbzd3vmWDZ8VMHf1SueiAaChfvH0yLvwu02sp-QU-tljGYBTJ8Pr1jWQIG-o39XRrBSMis",
   "refresh_token":"dde2a67f-d99f-3f03-810b-1fcae59245de",
   "scope":"default",
   "token_type":"Bearer",
   "expires_in":86400
}

Autenticação com Password Grant

Todos os trechos de código na documentação da API do VBC utilizam o tipo de concessão de senha em vez do recomendado authorization_code para facilitar sua execução. Esse tipo de concessão não exige que você implemente uma URL de retorno de chamada. Em vez disso, você fornece seu nome de usuário e senha do VBC para solicitar um token.

Substitua os seguintes marcadores de lugar no exemplo pelos seus próprios valores:

VBC_USERNAME - Seu nome de usuário do Vonage Business Communications
VBC_PASSWORD - Sua senha do Vonage Business Communications
CONSUMER_KEY - A chave de consumidor que você gerou na etapa 5 acima
CONSUMER_SECRET - O “Segredo do Consumidor” que você gerou na etapa 5 acima

Observação: Ao usar a concessão de senha, você precisará acrescentar @vbc.prod ao seu nome de usuário.

Aviso: Não utilize as credenciais do seu Account de desenvolvedor do VBC (*.api) para a solicitação de token. Você deve usar as credenciais do seu usuário do VBC para VBC_USERNAME e VBC_PASSWORD.

curl --request POST 'https://api.vonage.com/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=password' \ --data-urlencode 'scope=openid' \ --data-urlencode 'username=$VBC_USERNAME@vbc.prod' \ --data-urlencode 'password=$VBC_PASSWORD' \ --data-urlencode 'client_id=$VBC_CLIENT_ID' \ --data-urlencode 'client_secret=$VBC_CLIENT_SECRET'

Ao executá-lo, você receberá uma resposta em JSON com o access_token incorporado nele. Você precisa desse token para usar as APIs de Account, Extensão e Usuário:

{
    "access_token": "xyz123eyJ4NQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFemhrWmciLCJraWQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFNemhrWmciLCJhbGciOiJSUzI1NiJ9..gs7JO2RLPFIld7NXM9gnOy9CYaLs_EYXJJilxX76MFBiidoiG9sIW4RkeHLvDVLyFP1eVd_Pt7000wAr13mcXn-6x6D9oJeAH_Iz8nbzd3vmWDZ8VMHf1SueiAaChfvH0yLvwu02sp-QU-tljGYBTJ8Pr1jWQIG-o39XRrBSMis",
    "refresh_token": "abc123-5903-3513-8d27-333daf581837",
    "scope": "openid",
    "id_token": "abc123eyJ4NQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFemhrWmciLCJraWQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFNemhrWmciLCJhbGciOiJSUzI1NiJ9..gs7JO2RLPFIld7NXM9gnOy9CYaLs_EYXJJilxX76MFBiidoiG9sIW4RkeHLvDVLyFP1eVd_Pt7000wAr13mcXn-6x6D9oJeAH_Iz8nbzd3vmWDZ8VMHf1SueiAaChfvH0yLvwu02sp-QU-tljGYBTJ8Pr1jWQIG-o39XRrBSMis",
    "token_type": "Bearer",
    "expires_in": 82566
}

Validade do token

Token de acesso - Os tokens de acesso expiram após 24 horas (86.400 segundos). Após a expiração de um token de acesso, você precisará usar o token de atualização com o tipo de concessão “refresh” para solicitar um novo token de acesso.
Token de atualização - Os tokens de atualização expiram após 7 dias (604.800 segundos). Depois que um token de atualização é trocado por um token de acesso, ele deixa de ser válido, e um novo token de atualização é fornecido. Se o token de atualização não for utilizado dentro do prazo de validade, será necessário realizar uma nova autenticação.

Como usar o token de atualização

Quando o token de acesso expirar, você precisará gerar um novo token de acesso usando o token de atualização. O token de atualização será enviado quando você fizer sua primeira solicitação ao /token ponto final.

Para regenerar o token de acesso:

curl --location --request POST 'https://api.vonage.com/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=refresh_token' \ --data-urlencode 'client_id=$VBC_CLIENT_ID' \ --data-urlencode 'client_secret=$VBC_CLIENT_SECRET' \ --data-urlencode 'refresh_token=$REFRESH_TOKEN'

Substitua os seguintes marcadores de lugar no exemplo pelos seus próprios valores:

VBC_CLIENT_ID - O ID do cliente do seu aplicativo de desenvolvedor
VBC_CLIENT_SECRET - O código secreto do seu aplicativo de desenvolvedor
REFRESH_TOKEN - O token de atualização da sua solicitação inicial para obter um token de acesso.

Isso retornará um novo token de acesso e um novo token de atualização

{
   "access_token": "xyz123eyJ4NQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFemhrWmciLCJraWQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFNemhrWmciLCJhbGciOiJSUzI1NiJ9..gs7JO2RLPFIld7NXM9gnOy9CYaLs_EYXJJilxX76MFBiidoiG9sIW4RkeHLvDVLyFP1eVd_Pt7000wAr13mcXn-6x6D9oJeAH_Iz8nbzd3vmWDZ8VMHf1SueiAaChfvH0yLvwu02sp-QU-tljGYBTJ8Pr1jWQIG-o39XRrBSMis",
    "refresh_token": "abc123-5903-3513-8d27-333daf581837",
    "scope": "openid",
    "id_token": "abc123eyJ4NXQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFNemhrWmciLCJraWQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFNemhrWmciLCJhbGciOiJSUzI1NiJ9..kpFXRg4qSW9sntliysg-3EGO8KwZ8Vk5jGvOwqq0gJEyPQHL5BQKKrF799VL6Z9OJfCne564N42UWnrQqUmNyU0q8l0td1E3zPA0L5iQQEbaVsbxRf5NCZUwYY9Pb7bXjINCiGF4Xy7wCw2SRpv9iQvg3G68qI5Z8f_25QmxSTY",
    "token_type": "Bearer",
    "expires_in": 86400
}

Para todas as solicitações de API a partir de agora, você precisará usar este token de acesso. Quando este token de acesso expirar, você precisará gerar um novo token de acesso usando o token de atualização mais recente.

Próximos passos

Agora que você criou um token de acesso, está pronto para fazer uma solicitação à API.