OAuth 2.0

L'API seven.io peut être utilisée pour l'authentification et l'autorisation en utilisant le protocole OAuth 2.0 pour permettre aux utilisateurs de votre logiciel d'intégrer facilement et directement notre service.

Principes de base

OAuth 2.0 permet à votre application d'obtenir des droits d'accès aux comptes clients afin d'envoyer des requêtes API directement en leur nom.

Pour cela, vous devez d'abord enregistrer votre application chez nous. Vous le faites vous-même dans le tableau de bord sous Développeur > Applications OAuth. Vous y renseignez le nom, l'URL de redirection (redirect_uri) et les portées souhaitées, et vous recevez client_id et client_secret comme données d'accès à notre API OAuth 2.0.

Le client_secret ne vous est affiché qu'une seule fois, juste après la création, et nous le stockons uniquement sous forme de hachage. Conservez-le en lieu sûr. Si vous le perdez, vous pouvez en générer un nouveau dans le tableau de bord - l'ancien devient alors invalide.

Toutes les applications fonctionnent maintenant selon le modèle suivant lors de l'accès à notre API avec OAuth 2.0 :

• D'abord, vous devez obtenir l'autorisation du client. Pour cela, vous redirigez le client vers une page spéciale sur notre site, où le client doit se connecter et accorder l'accès à votre application.
• Après avoir confirmé ou rejeté la demande d'autorisation, le client est renvoyé vers votre application. Si le client accorde l'autorisation, votre application recevra un code d'autorisation.
• Avec ce code d'autorisation, votre application peut récupérer le jeton d'accès via notre API OAuth 2.0, qui permet l'accès direct à nos APIs.

Les jetons d'accès ont une durée de vie limitée d'une heure par défaut. Si votre application nécessite un accès à nos APIs au-delà de la durée de vie d'un seul jeton d'accès, elle peut récupérer de nouveaux jetons d'accès en utilisant le jeton de rafraîchissement.

Processus

Récupérer le jeton d'accès

Si tout a fonctionné jusqu'à présent, vous pouvez maintenant utiliser le paramètre GET code de l'étape 3. pour récupérer un jeton d'accès comme suit :

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

En cas de succès, vous recevrez des données au format JSON comme suit :

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

Mettre à jour le jeton d'accès

Pour mettre à jour le jeton d'accès, appelez l'API OAuth 2.0 comme suit :

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

En cas de succès, vous recevrez de nouvelles données de jeton au format JSON comme suit :

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

Révoquer le jeton

Pour révoquer un jeton d'accès ou un jeton de rafraîchissement, appelez l'API OAuth 2.0 comme suit :

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

En cas de succès, vous recevrez une réponse au format JSON comme suit :

{
  "revoked": true
}

En cas d'erreur, le serveur répond avec le code d'état HTTP 400 :

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

Remarque : Pour des raisons de sécurité, le serveur répondra avec 200 OK même si le jeton était déjà invalide ou appartient à un autre client.

Accès à nos APIs

Appelez nos APIs selon la documentation respective et envoyez le jeton d'accès dans l'Authorization Header sans encodage supplémentaire (pas de base64 ou similaire).

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

Vous pouvez également tester la connexion réussie via OAuth 2.0 en utilisant l'appel suivant :

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

Portées

Les portées d'application suivantes peuvent être demandées par le client :

Plusieurs portées peuvent être spécifiées en utilisant un espace encodé en url. Si la portée n'est pas spécifiée ou est vide, les portées que vous avez enregistrées pour l'application sont appliquées. Vous ne pouvez demander que des portées enregistrées pour votre application - tout le reste est refusé avec invalid_scope.

Applications vérifiées et non vérifiées

Les applications que vous créez vous-même sont d'abord non vérifiées. Elles sont immédiatement pleinement fonctionnelles, mais deux restrictions s'appliquent :

• Les comptes tiers voient sur la page d'autorisation une remarque indiquant que l'application n'a pas été vérifiée par seven.
• L'application peut se connecter à 25 comptes tiers au maximum. Une fois cette limite atteinte, l'autorisation de comptes supplémentaires échoue. Votre propre compte et vos sous-comptes ne sont pas comptabilisés, vous pouvez donc tester sans restriction.

De plus, chaque compte peut posséder au maximum 10 applications non vérifiées. Les applications vérifiées ne sont pas comptabilisées.

Dès que votre application doit travailler en production avec des comptes tiers, demandez une vérification dans le tableau de bord. Une condition préalable est d'avoir renseigné un site web. Nous examinons le nom, le logo, le site web et les portées demandées et, après une vérification réussie, nous supprimons aussi bien la remarque que la limite.

Exemple de code PHP

Voici un exemple simple en PHP. Dans le premier code, l'URL OAuth est générée et le client y est dirigé :

<?php

// Identifiants de l'application
$client_id = 'testclient';
$client_secret = 'testsecret';

session_start();

// Demander l'autorisation pour les points de terminaison sms, analytics et lookup. // Laisser vide pour permettre toutes les portées
$requested_scopes = [
  'sms',
  'analytics',
  'lookup'
];

// Générer une chaîne aléatoire pour state
$state = bin2hex(openssl_random_pseudo_bytes(10));

// Stocker state dans la session
$_SESSION['state'] = $state;

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

// Rediriger l'utilisateur vers le site d'autorisation OAuth
header('Location: ' . $auth_uri);

Le deuxième code est la page qui s'exécute sous votre redirect_uri. Ici l'autorisation est vérifiée et les jetons sont récupérés :

<?php

// Identifiants de l'application 
$client_id = 'testclient'; 
$client_secret = 'testsecret'; 

session_start(); 

// Échec de la vérification CSRF
if($_GET['state'] != $_SESSION['state']) {
  die('Échec de la vérification CSRF');
}

// Une erreur s'est produite pendant l'autorisation
elseif(isset($_GET['error'])) {
  die('Erreur: ' . $_GET['error']);
}

// Nous avons reçu un code, l'envoyer à l'API OAuth 2.0 pour obtenir les jetons...
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);

  // Vous devriez stocker les jetons ici pour effectuer des appels API
  die("Jeton d'accès: " . $token->access_token);
}