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. Você mesmo faz isso no painel, em Desenvolvedor > Aplicativos OAuth. Lá você define o nome, a URL de redirecionamento (redirect_uri) e os escopos desejados, e recebe client_id e client_secret como suas credenciais de acesso à nossa API OAuth 2.0.

O client_secret é exibido apenas uma vez, logo após a criação, e é armazenado por nós somente como hash. Guarde-o em local seguro. Se você perdê-lo, pode gerar um novo no painel - o antigo se torna inválido nesse momento.

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

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:

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:

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

Atualizar token de acesso

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

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:

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

Revogar token

Para revogar um token de acesso ou de atualização, acesse a API OAuth 2.0 da seguinte forma:

curl -u testclient:testsecret https://oauth.seven.io/revoke \
  -d "token=b1a9391d0469cafe30258893ab6025d4ad94ecec"

Em caso de sucesso, você receberá uma resposta no formato JSON como segue:

{
  "revoked": true
}

Em caso de erro, o servidor responde com o código de status HTTP 400:

{
  "error": "invalid_client",
  "error_description": "The client credentials are invalid"
}

Nota: Por razões de segurança, o servidor responderá com 200 OK mesmo se o token já era inválido ou pertence a outro cliente.

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:

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

{
    "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:

Vários escopos podem ser indicados por um espaço codificado em URL. Se o escopo não for especificado ou estiver vazio, valem os escopos que você registrou para o aplicativo. Na solicitação de autorização você só pode requisitar escopos que estejam registrados para o seu aplicativo - qualquer outro é recusado com invalid_scope.

Aplicativos verificados e não verificados

Aplicativos criados por você mesmo são inicialmente não verificados. Eles são totalmente funcionais desde o primeiro momento, mas estão sujeitos a duas limitações:

• Contas de terceiros veem na página de autorização um aviso de que o aplicativo não foi verificado pela seven.
• O aplicativo pode se conectar a no máximo 25 contas de terceiros. Ao atingir esse limite, a autorização de novas contas falha. Sua própria conta e suas subcontas não são contabilizadas, portanto você pode testar sem restrições.

Além disso, cada conta pode ter no máximo 10 aplicativos não verificados. Aplicativos verificados não entram nessa contagem.

Assim que seu aplicativo for entrar em produção com contas de terceiros, solicite uma verificação no painel. Para isso é necessário ter um site registrado. Analisamos o nome, o logotipo, o site e os escopos solicitados e, após a verificação bem-sucedida, removemos tanto o aviso quanto o limite.

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:

<?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:

<?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);
}