1. Home
  2. Gateway
  3. HTTP API
  4. OAuth 2.0

OAuth 2.0

Die sms77.io API kann unter Verwendung des OAuth 2.0 Protokolls zur Authentifizierung und Autorisierung genutzt werden, um Nutzern Ihrer Software eine leichte und direkte Integration unseres Services zu ermöglichen.

Grundlagen

Durch OAuth 2.0 kann Ihre Applikation Zugriffsrechte auf Accounts von Kunden erlangen, um API Anfragen direkt in deren Namen an uns zusenden.

Hierzu müssen Sie vorab Ihre Applikation bei uns registrieren. Diese erhalten Sie derzeit nur von unserem Support. Bitte geben Sie Ihre Umleitungs URL (redirect_uri)  an. Sie erhalten client_id und client_secret als Ihre Zugangsdaten zu unserer OAuth 2.0 API.

Alle Anwendungen laufen nun nach folgendem Muster beim Zugriff auf unsere API mit OAuth 2.0 ab:

  • Zunächst müssen Sie vom Kunden die Autorisierung einholen. Hierzu leiten Sie diesen auf eine spezielle Seite bei uns um, auf welcher der Kunde sich einloggen und Ihrer Anwendung den Zugriff gestatten muss.
  • Nach Bestätigung oder Ablehnung der Autorisierungsanfrage wird der Kunde wieder zu Ihrer Applikation zurückgeschickt. Sofern der Kunde die Genehmigung erteilt, erhält Ihre Applikation einen Autorisierungscode.
  • Mit diesem Autorisierungscode kann Ihre Anwendung über unsere OAuth 2.0 API das Zugriffstoken abrufen, mit welchem der direkte Zugriff auf unsere APIs möglich ist.

Zugriffstoken haben eine begrenzte Lebensdauer von standardmäßig einer Stunde. Wenn Ihre Anwendung über die Lebensdauer eines einzelnen Zugriffstokens hinaus Zugriff auf unsere APIs benötigt, kann diese mittels des Aktualisierungstokens Ihre Anwendung neue Zugriffstoken abrufen.

Beispiel

1. Applikation einrichten

Sie erhalten von uns als Zugangsdaten zur OAuth 2.0 API folgende Zugangsdaten:

client_id testclient
client_secret testsecret

Die von Ihnen bereitgestellte redirect_uri lautet https://acme.inc/oauth_redirect

2. Kunde an OAuth 2.0 Autorisierungsseite weiterleiten

Leiten Sie Ihre Kunden zu folgender URL weiter:

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

state ist dabei ein zufälliger String und dient der Vermeidung von CSRF Angriffen.
scope ist der angeforderte Geltungsbereich, auf welchen Sie Zugriff vom Kunden haben möchten – in diesem Fall der Versand von SMS und die Abfrage von Statistiken.

3. Kunde wird zu Ihrer Applikation zurückgeschickt

Nachdem der Kunde die Autorisierung erteilt (oder verweigert) hat, leiten wir diesen automatisch zu Ihrer redirect_uri mit einigen zusätzlichen GET Parameter um.

Im Erfolgsfall:

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

Im Fehlerfall
:

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

Sie sollten hier auf jeden Fall überprüfen, ob state den von Ihnen im zweiten Schritt erstellten Wert entspricht, um CSRF zu vermeiden.

4. Zugriffstoken abrufen

Hat alles bis hierhin geklappt, können Sie nun mit dem GET Parameter code aus Schritt 3. ein Zugriffstoken wie folgt abrufen:

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

Sie erhalten im im Erfolgsfall Daten im JSON-Format wie folgt zurück:

{"access_token":"b1a9391d0469cafe30258893ab6025d4ad94ecec","expires_in":3600,"token_type":"Bearer","scope":"sms","refresh_token":"ffd8e622aa5dccc2905f2ac6a0999c785a803157"}
5. Zugriffstoken aktualisieren

Um den Zugriffstoken zu aktualisieren, rufen Sie die OAuth 2.0 API wie folgt auf:

curl -u testclient:testpass https://oauth.sms77.io/token -d 'grant_type=refresh_token&refresh_token=ffd8e622aa5dccc2905f2ac6a0999c785a803157'

Sie erhalten im im Erfolgsfall Daten neue Token im JSON-Format wie folgt zurück:

{"access_token":"worw5xlrl0sjwqkvmstibwn4pw0mdvpddljzkfi8","expires_in":3600,"token_type":"Bearer","scope":"sms","refresh_token":"n94c2kyej8ycsjutmviuk8i6zebgsda0uzg2gbpn"}
6. Zugriff auf unsere APIs

Rufen Sie unsere APIs entsprechend der jeweiligen Dokumentation auf und senden Sie den Zugriffstoken im  Authorization Header  ohne weitere Kodierung (kein bas64 o.ä.).

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

Weiterhin können Sie die Erfolgreiche Anbindung per OAuth 2.0 über folgenden Aufruf testen:

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

Antwort:

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

Geltungsbereiche

Die folgenden Geltungsbereiche können Sie vom Kunden anfordern lassen:

Geltungsbereich Bedeutung
analytics Abfrage von Statistiken
balance Guthaben abfragen
contacts Kontakte abfragen und bearbeiten
hooks Erlaubt das Ändern und Einsehen von Webhooks
journal Ihr Logbuch abfragen
lookup Anfragen per Lookup (HLR, MNP etc.) durchführen
pricing Preise des Accounts abfragen
sms Versand von SMS Nachrichten
status Statusbericht von SMS abfragen
subaccounts Subaccounts bearbeiten und einsehen
validate_for_voice Rufnummern als Absender für Voice verifizieren
voice Voice Nachrichten versenden

Mehrere Geltungsbereiche können dabei durch ein urlkodiertes Leerzeichen angegeben werden. Sofern der Geltungsbereich nicht angegeben wird bzw. leer ist, wird der Standardgeltungsbereich angewendet.

 

PHP Code Beispiel

Hier ein einfach gehaltenes Beispiel in PHP.

Im ersten Code wird die OAuth URL generiert und der Kunde an diese weitergeleitet:

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

Beim zweiten Code handelt es sich um die Seite, die unter Ihrer redirect_uri läuft. Hier wird die Autorisierung überprüft und die Tokens werden abgerufen:

<?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.sms77.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);
}
Menü