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 ne pouvez actuellement l'obtenir que via notre support. Veuillez entrer votre URL de redirection (redirect_uri). Vous recevrez client_id et client_secret comme données d'accès à notre API OAuth 2.0.

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

  1. 1

    Configurer l'application

    Vous recevrez les données d'accès suivantes pour l'API OAuth 2.0 de notre part :

    • Name
      client_id
      Type
      string
      Description

      Votre ID d'accès - en règle générale, nous définissons ici le nom de votre app. Dans l'exemple ici, c'est testclient.

    • Name
      client_secret
      Type
      string
      Description

      Mot de passe d'accès pour l'API OAuth2.0. Dans l'exemple ici, c'est testsecret.

    De plus, vous devez nous fournir une redirect_uri vers laquelle nous redirigerons après autorisation. Dans notre exemple ici, l'URL est https://acme.inc/oauth_redirect

  2. 2

    Rediriger le client vers la page d'autorisation OAuth 2.0

    Dirigez vos clients vers l'URL suivante :

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

    • Name
      state
      Type
      string
      Description

      Une chaîne générée aléatoirement pour prévenir les attaques CSRF. Veuillez utiliser une chaîne cryptographiquement sécurisée à cette fin.

    • Name
      scope
      Type
      string
      Description

      La portée demandée à laquelle vous souhaitez avoir accès - dans ce cas l'envoi de SMS et la récupération de statistiques. Plusieurs portées peuvent être passées séparées par des espaces.

  3. 3

    Le client est renvoyé vers votre application

    Après que le client ait accordé (ou refusé) l'autorisation, nous le redirigeons automatiquement vers votre redirect_uri avec quelques paramètres GET supplémentaires.

    En cas de succès :

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

    En cas d'erreur :

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

    Vous devriez toujours vérifier ici si state correspond à la valeur que vous avez créée dans la deuxième étape afin d'éviter CSRF.

  4. 4

    Interroger le jeton d'accès

    Récupérez le jeton d'accès et le jeton de rafraîchissement via notre API OAuth 2.0.

POST/token

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 :

Requête

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 :

Réponse

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

Mettre à jour le jeton d'accès

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

Requête

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 :

Réponse

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

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 :

Requête

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

Réponse

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

PortéeSignification
analyticsInterroger les statistiques
balanceInterroger le solde de crédit
contactsInterroger et modifier les contacts
hooksPermet de modifier et voir les webhooks
journalInterroger votre journal
lookupExécuter des requêtes via lookup (HLR, MNP etc.)
pricinginterroger les prix du compte
rcsEnvoi de messages RCS
smsEnvoi de messages SMS
statusInterroger le rapport de statut SMS
subaccountsModifier et voir les sous-comptes
validate_for_voiceVérifier les numéros de téléphone comme expéditeur pour la voix
voiceEnvoyer des messages vocaux

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, la portée standard est appliquée.

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

Rediriger le client vers la page OAuth2.0

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

Vérification de l'autorisation et récupération des jetons

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