OAuth 2.0

La API de seven.io se puede utilizar para autenticación y autorización mediante el protocolo OAuth 2.0, para permitir a los usuarios de su software una integración fácil y directa de nuestro servicio.

Fundamentos

A través de OAuth 2.0, su aplicación puede obtener derechos de acceso a las cuentas de los clientes para enviar solicitudes de API directamente en su nombre.

Para ello, primero debe registrar su aplicación con nosotros. Esto lo hace usted mismo en el dashboard, en Desarrollador > Aplicaciones OAuth. Allí indica el nombre, la URL de redirección (redirect_uri) y los alcances que necesita, y recibe client_id y client_secret como sus credenciales para nuestra API OAuth 2.0.

El client_secret se muestra una sola vez, justo después de crear la aplicación, y nosotros solo guardamos un hash del mismo. Consérvelo en un lugar seguro. Si lo pierde, puede generar uno nuevo en el dashboard, con lo que el anterior queda invalidado.

Todas las aplicaciones ahora siguen el siguiente patrón al acceder a nuestra API con OAuth 2.0:

• Primero, debe obtener la autorización del cliente. Para ello, rediríjalo a una página especial en nuestro sitio, donde el cliente debe iniciar sesión y permitir el acceso a su aplicación.
• Después de la confirmación o rechazo de la solicitud de autorización, el cliente será redirigido de nuevo a su aplicación. Si el cliente otorga el permiso, su aplicación recibirá un código de autorización.
• Con este código de autorización, su aplicación puede obtener el token de acceso a través de nuestra API OAuth 2.0, lo que permite el acceso directo a nuestras APIs.

Los tokens de acceso tienen una vida útil limitada de una hora por defecto. Si su aplicación necesita acceso a nuestras APIs más allá de la vida útil de un solo token de acceso, puede obtener nuevos tokens de acceso mediante el token de actualización.

Proceso

Obtener el token de acceso

Si todo ha funcionado hasta aquí, ahora puede obtener un token de acceso con el parámetro GET code del paso 3 de la siguiente manera:

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

En caso de éxito, recibirá datos en formato JSON como sigue:

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

Actualizar el token de acceso

Para actualizar el token de acceso, llame a la API OAuth 2.0 de la siguiente manera:

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

En caso de éxito, recibirá nuevos tokens en formato JSON como sigue:

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

Revocar token

Para revocar un token de acceso o de actualización, llame a la API OAuth 2.0 de la siguiente manera:

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

En caso de éxito, recibirá una respuesta en formato JSON como sigue:

{
  "revoked": true
}

En caso de error, el servidor responde con el código de estado HTTP 400:

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

Nota: Por razones de seguridad, el servidor responderá con 200 OK incluso si el token ya era inválido o pertenece a otro cliente.

Acceso a nuestras APIs

Acceda a nuestras APIs de acuerdo con la documentación correspondiente y envíe el token de acceso en el Authorization Header sin codificación adicional (sin base64 u otros).

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

Además, puede probar la conexión exitosa a través de OAuth 2.0 con la siguiente llamada:

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"
}

Alcances

Puede solicitar al cliente los siguientes alcances:

Varios ámbitos pueden especificarse mediante un espacio codificado en URL. Si no se especifica el ámbito o está vacío, se aplicarán los ámbitos que haya registrado para la aplicación. En la solicitud de autorización solo puede pedir ámbitos que estén registrados para su aplicación - cualquier otro se rechaza con invalid_scope.

Aplicaciones verificadas y no verificadas

Las aplicaciones que usted mismo crea están inicialmente sin verificar. Son plenamente funcionales de inmediato, pero están sujetas a dos limitaciones:

• Las cuentas ajenas ven en la página de autorización un aviso de que la aplicación no ha sido verificada por seven.
• La aplicación puede conectarse como máximo con 25 cuentas ajenas. Una vez alcanzado ese límite, la autorización de más cuentas falla. Su propia cuenta y sus subcuentas no cuentan para el límite, por lo que puede hacer pruebas sin restricciones.

Además, cada cuenta puede tener como máximo 10 aplicaciones sin verificar. Las aplicaciones verificadas no cuentan para ese límite.

En cuanto su aplicación vaya a trabajar en producción con cuentas ajenas, solicite una verificación en el dashboard. Para ello es necesario haber indicado un sitio web. Revisamos el nombre, el logotipo, el sitio web y los ámbitos solicitados y, tras una verificación exitosa, eliminamos tanto el aviso como el límite de conexiones.

Ejemplo de código PHP

Aquí hay un ejemplo sencillo en PHP. En el primer código se genera la URL de OAuth y el cliente es redirigido a ella:

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

El segundo código corresponde a la página que se ejecuta bajo su redirect_uri. Aquí se verifica la autorización y se recuperan los 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);
}