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