OAuth 2.0

The sms77.io API can be used using the OAuth 2.0 protocol for authentication and authorization to allow users of your software an easy and direct integration of our service.

Basics

Using OAuth 2.0, your application can gain access rights to customers’ accounts in order to send API requests directly to us on their behalf. To do this, you must first register your application with us. You can currently only get this from our support. Please enter your redirect URL(redirect_uri). You will receive client_id and client_secret as your access data to our OAuth 2.0 API. All applications will now run according to the following pattern when accessing our API with OAuth 2.0:

First, you need to obtain authorization from the customer. To do this, you redirect them to a special page at our site, where the customer must log in and allow access to your application.
After confirming or denying the authorization request, the customer is sent back to your application. Provided the customer approves, your application will receive an authorization code.
With this authorization code, your application can retrieve the access token via our OAuth 2.0 API, which allows direct access to our APIs.

Access tokens have a limited lifetime of one hour by default. If your application needs access to our APIs beyond the lifetime of a single access token, it can retrieve new access tokens using your application’s refresh to ken.

Example

1. Application setup

You will receive the following access tokens from us as credentials to the OAuth 2.0 API:

`client_id`	testclient
`client_secret`	testsecret

The redirect_uri you provide is https://acme.inc/oauth_redirect

2. Redirect customer to OAuth 2.0 authorization page

Redirect your customers to the following URL:

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

state is a random string and is used to avoid CSRF attacks.

scope is the requested scope you want to have access to from the customer – in this case sending SMS and requesting statistics.

3. Customer is sent back to your application

After the customer grants (or denies) authorization, we automatically redirect him to your redirect_uri with some additional GET parameters.

In case of success:

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

In case of failure:

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

You should definitely check here if state matches the value you created in the second step to avoid CSRF.

4. Retrieve access token

If everything has worked so far, you can now use the GET parameter code from step 3. to retrieve an access token as follows:

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

You will get back data in JSON format as follows in case of success:

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

5. Refresh access token

To update the access token, call the OAuth 2.0 API as follows:

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

You will get back in success case data new token in JSON format as follows:

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

6. Accessing our APIs

Call our APIs according to the respective documentation and send the access token in the Authorization header without any further encoding (no bas64 or similar).

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

Furthermore you can test the successful connection via OAuth 2.0 with the following call:

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

Response:

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

Scopes

You can request the following scopes from the customer:

Scope	Meaning
`analytics`	Query statistics
`balance`	Query balance
`contacts`	Query and edit contacts
`hooks`	Allow to change and view webhooks
`journal`	Query your logbook
`lookup`	Perform lookup requests (HLR, MNP etc.)
`pricing`	Query prices of the account
`sms`	Send SMS messages
`status`	Query status report of SMS
`subaccounts`	Edit and view subaccounts
`validate_for_voice`	Verify phone numbers as originators for voice
`voice`	Send voice messages

Multiple scopes can be specified using a url-coded blank character. If the scope is not specified or is empty, the default scope is used.

PHP Code sample

Here is a simple example in PHP.

In the first code, the OAuth URL is generated and the customer is redirected to it:

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

The second code is the page that runs under your redirect_uri. Here the authorization is checked and the tokens are retrieved:

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

Gateway