OAuth 2.0

A API seven.io pode ser utilizada para autenticação e autorização usando o protocolo OAuth 2.0, permitindo uma integração fácil e direta do nosso serviço aos usuários do seu software.

Fundamentos

Com o OAuth 2.0, sua aplicação pode obter permissões de acesso às contas dos clientes para enviar solicitações de API diretamente em nome deles.

Para isso, você deve registrar sua aplicação conosco previamente. Atualmente, você só pode obter isso com o nosso suporte. Por favor, forneça sua URL de redirecionamento (redirect_uri). Você receberá client_id e client_secret como suas credenciais de acesso à nossa API OAuth 2.0.

Todas as aplicações seguem agora o seguinte padrão ao acessar nossa API com OAuth 2.0:

  • Primeiro, você deve obter a autorização do cliente. Para isso, redirecione-o para uma página especial em nosso site, onde o cliente deve fazer login e permitir o acesso à sua aplicação.
  • Após a confirmação ou rejeição do pedido de autorização, o cliente será redirecionado de volta para sua aplicação. Se o cliente conceder a permissão, sua aplicação receberá um código de autorização.
  • Com este código de autorização, sua aplicação pode recuperar o token de acesso através da nossa API OAuth 2.0, permitindo o acesso direto às nossas APIs.

Os tokens de acesso têm uma vida útil limitada de, por padrão, uma hora. Se sua aplicação precisar de acesso às nossas APIs além da vida útil de um único token de acesso, ela pode recuperar novos tokens de acesso usando o token de atualização.

Processo

  1. 1

    Configurar a aplicação

    Você receberá de nós as seguintes credenciais de acesso à API OAuth 2.0:

    • Name
      client_id
      Type
      string
      Description

      Sua ID de acesso - geralmente usamos aqui o nome do seu aplicativo. No exemplo aqui é testclient.

    • Name
      client_secret
      Type
      string
      Description

      Senha de acesso para a API OAuth2.0. No exemplo aqui é testsecret.

    Além disso, você deve nos fornecer um redirect_uri para o qual redirecionaremos após a autorização. No nosso exemplo aqui, a URL é https://acme.inc/oauth_redirect

  2. 2

    Redirecionar cliente para a página de autorização OAuth 2.0

    Redirecione seus clientes para a seguinte URL:

    https://oauth.seven.io/authorize?response_type=code&client_id=testclient&state=xyz&scope=sms%20analytics

    • Name
      state
      Type
      string
      Description

      Uma string gerada aleatoriamente para prevenir ataques de CSRF. Por favor, use um string criptograficamente segura.

    • Name
      scope
      Type
      string
      Description

      O escopo solicitado ao qual você deseja acesso do cliente – neste caso, o envio de SMS e a consulta de estatísticas. Vários escopos podem ser passados separados por espaços.

  3. 3

    Cliente é redirecionado de volta para sua aplicação

    Após o cliente conceder (ou negar) a autorização, redirecionamos automaticamente para o seu redirect_uri com alguns parâmetros GET adicionais.

    Em caso de sucesso:

    https://acme.inc/oauth_redirect?code=9ccb478a7cbe043c1df211f1d52a6437f8756cf8&state=xyz

    Em caso de erro:

    https://acme.inc/oauth_redirect?error=access_denied&error_description=The+user+denied+access+to+your+application&state=xyz

    Você deve verificar aqui se state corresponde ao valor que você criou na segunda etapa, para evitar CSRF.

  4. 4

    Consultar token de acesso

    Recupere o token de acesso e o token de atualização através da nossa API OAuth 2.0.

POST/token

Obter token de acesso

Se tudo correu bem até aqui, você pode agora obter um token de acesso com o parâmetro GET code da etapa 3 da seguinte forma:

Requisição

curl -u testclient:testsecret https://oauth.seven.io/token \
  -d 'grant_type=authorization_code&code=9ccb478a7cbe043c1df211f1d52a6437f8756cf8'

Em caso de sucesso, você receberá os dados no formato JSON como segue:

Resposta

{
  "access_token":"b1a9391d0469cafe30258893ab6025d4ad94ecec",
  "expires_in":3600,
  "token_type":"Bearer",
  "scope":"sms",
  "refresh_token":"ffd8e622aa5dccc2905f2ac6a0999c785a803157"
}
POST/token

Atualizar token de acesso

Para atualizar o token de acesso, acesse a API OAuth 2.0 da seguinte forma:

Requisição

curl -u testclient:testsecret https://oauth.seven.io/token \
  -d 'grant_type=refresh_token&refresh_token=ffd8e622aa5dccc2905f2ac6a0999c785a803157'

Em caso de sucesso, você receberá novos tokens no formato JSON como segue:

Resposta

{
  "access_token":"worw5xlrl0sjwqkvmstibwn4pw0mdvpddljzkfi8",
  "expires_in":3600,
  "token_type":"Bearer",
  "scope":"sms",
  "refresh_token":"n94c2kyej8ycsjutmviuk8i6zebgsda0uzg2gbpn"
}

Acesso às nossas APIs

Acesse nossas APIs de acordo com a documentação correspondente e envie o token de acesso no Authorization Header sem qualquer codificação adicional (sem base64 ou similar).

curl https://gateway.seven.io/api/sms -H 'Authorization: Bearer ACCESS_TOKEN'

Além disso, você pode testar a conexão bem-sucedida via OAuth 2.0 com a seguinte chamada:

Requisição

curl https://oauth.seven.io/me -H 'Authorization: Bearer ACCESS_TOKEN'

Resposta

{
    "success": true,
    "user_id": 12345,
    "email": "john.doe@acme.inc",
    "company": "Acme Inc.",
    "alias": "acme_inc",
    "balance": "627.3615"
}

Escopos

Os seguintes escopos podem ser solicitados pelo cliente:

EscopoSignificado
analyticsConsulta de estatísticas
balanceConsultar saldo
contactsConsultar e editar contatos
hooksPermite alterar e visualizar webhooks
journalConsultar seu diário
lookupRealizar consultas por Lookup (HLR, MNP etc.)
pricingConsultar preços da conta
rcsEnvio de mensagens RCS
smsEnvio de mensagens SMS
statusConsultar relatório de status de SMS
subaccountsEditar e visualizar subcontas
validate_for_voiceVerificar números como remetente para Voice
voiceEnviar mensagens de voz

Vários escopos podem ser indicados por um espaço codificado em URL. Se o escopo não for especificado ou estiver vazio, o escopo padrão será aplicado.

Exemplo de Código PHP

Aqui está um exemplo simples em PHP. No primeiro código, a URL OAuth é gerada e o cliente é redirecionado para ela:

Redirecionar clientes para a página OAuth2.0

<?php

// Application credentials
$client_id = 'testclient';
$client_secret = 'testsecret';

session_start();

// Request authorization for sms, analytics and lookup endpoints. // Leave empty to allow all scopes
$requested_scopes = [
  'sms',
  'analytics',
  'lookup'
];

// Generate random string for state
$state = bin2hex(openssl_random_pseudo_bytes(10));

// Store state in session
$_SESSION['state'] = $state;

// Build authorization URI
$auth_uri = 'https://oauth.seven.io/authorize?' .
  http_build_query([
    'response_type' => 'code',
    'client_id' => $client_id,
    'state' => $state,
    'scope' => implode(' ', $requested_scopes),
  ]);

// Redirect User to OAuth authorization site
header('Location: ' . $auth_uri);

No segundo código, está a página que roda sob o seu redirect_uri. Aqui, a autorização é verificada e os tokens são recuperados:

Verificação da autorização e recuperação de tokens

<?php

// Application credentials $client_id = 'testclient'; 
$client_secret = 'testsecret'; 

session_start(); 

// CSRF check failed
if($_GET['state'] != $_SESSION['state']) {
  die('CSRF check failed');
}

// An error occured during authorization
elseif(isset($_GET['error'])) {
  die('Error: ' . $_GET['error']);
}

// We got a code, send it to OAuth 2.0 API to get the tokens...
elseif(isset($_GET['code'])) {
  $post_vars = http_build_query([
    'grant_type' => 'authorization_code',
    'code' => $_GET['code'],
  ]);

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_USERPWD, $client_id . ":" . $client_secret);

  curl_setopt($ch, CURLOPT_URL, 'https://oauth.seven.io/token');
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $post_vars);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  $response = curl_exec($ch);

  curl_close ($ch);

  $token = json_decode($response);

  // You should store the tokens here in order to make API calls
  die("Access Token: " . $token->access_token);
}