OAuth2

Overview

OAuth2 is an authorization protocol that allows users to exchange data with third-party applications, without sharing their password and by limiting access.

The following instructions provide detailed steps to help you use Keyyo APIs.

For more details about OAuth2, refer to the OAuth 2.0 framework RFC 6750.

Server Side

The following workflow shows the process to get an access token the first time (you'll also get a refresh token):
OAuth workflow

Because an access token expires, when it happens, you need to ask for a new one with the refresh token you got in step 2.
The following workflow shows the process to get a new access token by exchanging your refresh token:
OAuth workflow
First, you need to register your app before starting.

Get the authorization code (1)

Method Endpoint
GET https://ssl.keyyo.com/oauth2/authorize.php

Parameters

Name Required Description
client_id YES The client app identifier
response_type YES The value must be set to code
state YES This value contains a unique random string used against CSRF (Cross-Site Request Forgery) attacks
scopes NO The list of permissions separated by commas
redirect_uri YES The callback URL defined in your application settings

Example

  • PHP
			
$client_id = "<Your client identifier>";
$keyyo_authorize_endpoint = "https://ssl.keyyo.com/oauth2/authorize.php";

// Redirect the browser to Keyyo's login/authorization form
$_SESSION["auth_state"] = uniqid();
$authorize_url = sprintf("%s?client_id=%s&response_type=code&state=%s&redirect_uri=%s", $keyyo_authorize_endpoint, $client_id, $_SESSION["auth_state"]), "https://domain.com/callback");
header("Location: " . $authorize_url);
			
		

Response

You will be redirected to your callback URL defined in your application settings.

Exemple: http://www.domain.com/callback.php?code=<Your code>&state=<Your state>

Name Description
code The authorization code returned
state Your state value

At this time, you will receive an authorization code and the previous state passed as a parameter in the URL.
Exchange these values to get the refresh token and your first access token.

Warning : If states don't match, it's probably a CSRF attack and the process must be aborted.

Get the refresh token (2)

Method Endpoint
POST https://api.keyyo.com/oauth2/token.php

Parameters

Name Required Description
client_id YES The client app identifier
client_secret YES The client app secret
code YES The previous code received
grant_type YES The value must be set to authorization_code
state YES The value must match with the state value of your previous request

Example

  • PHP
			
$client_id = "<Your client identifier>"
$client_secret = "<Your client secret>"
$keyyo_token_endpoint = "https://api.keyyo.com/oauth2/token.php";

if (!isset($_GET["state"]) || (isset($_GET["state"]) && $_GET["state"] != $_SESSION["auth_state"])) {
	header("Content-Type: application/json");
	die(json_encode(["error" => "invalid_state", "error_description" => "Invalid state"]));
}

// Send a cURL request using request"s authorization code
$curl = curl_init($keyyo_token_endpoint);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, array(
	"client_id"     => $client_id,
	"client_secret" => $client_secret,
	"grant_type"    => "authorization_code",
	"redirect_uri"	=> $redirect_uri,
	"code"          => $_GET["code"]
));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);

$auth_data = curl_exec($curl);

// Retrieve the access token
if ($auth_data === false)
	die("cURL request failed");

$response = json_decode($auth_data);
if (is_null($response))
	die("Could not parse cURL response body.");

if (isset($response->error))
	die(isset($response->error_description) ? $response->error_description : $response->error);

// Output the access token and its lifetime
echo "Your access token is: ", $response->access_token, "<br />";
echo "It expires in: ", $response->expires_in, " seconds <br />";
			
		

Response

  • PHP
			
{ "access_token":"<Your access token>","expires_in":3600,"token_type":"bearer","scope":"a.user o.w.voipprofile","refresh_token":"<Your refresh token>" }
			
		
Name Description
access_token An acces token (IMPORTANT: You can use this access token to start consuming the API in step 3 but it will expires, and when it does, see step 4 on how to use the refresh token to obtain a new one.)
expires_in The access token expiration (in seconds)
token_type Bearer (meaning access_token is generated and send back you)
scope The scope list that you have defined in the OAuth authorization page
refresh_token The refresh token (IMPORTANT: When your access token expires, see step 4 on how to use the refresh token to obtain a new one.)

Consume the API with an access token (3)

To use REST Keyyo APIs, we advise you to use Keyyo Manager library available on Github.
For more information, you can refer to its documentation.

Example

  • PHP
			
$access_token = "<Your access token>";
$keyyo_manager = new \Keyyo\Manager\Client("1.0", $access_token);

// Retrieve all services from the authenticated customer
$services = $keyyo_manager->services();

// Loop over their services
foreach ($services as $service) {
	// ...
}
			
		

Get a new access token with the refresh token (4)

When your access token has expired, you should use your refresh token to get a new one.

Method Endpoint
POST https://api.keyyo.com/oauth2/token.php

Parameters

Name Required Description
client_id YES The client app identifier
client_secret YES The client app secret
grant_type YES The value must be set to refresh_token
refresh_token YES The refresh token obtained during step 2
redirect_uri YES The callback URL defined in your application settings

Example

  • PHP
			
$client_id = "<Your client identifier>";
$client_secret = "<Your client secret>";
$redirect_uri = "https://www.domain.com/callback";
$refresh_token = "<Your refresh token>";
$keyyo_token_endpoint = "https://api.keyyo.com/oauth2/token.php";

// Send a cURL request using request"s authorization code
$curl = curl_init($keyyo_token_endpoint);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, array(
	"client_id"     => $client_id,
	"client_secret" => $client_secret,
	"grant_type"    => "refresh_token",
	"refresh_token" => $refresh_token,
	"redirect_uri"  => $redirect_uri
));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);

$auth_data = curl_exec($curl);

// Retrieve the access token
if ($auth_data === false)
	die("cURL request failed");

$response = json_decode($auth_data);
if (is_null($response))
	die("Could not parse cURL response body.");

if (isset($response->error))
	die(isset($response->error_description) ? $response->error_description : $response->error);

// Output the access token and its lifetime
echo "Your access token is: ", $response->access_token, "<br />";
echo "It expires in: ", $response->expires_in, " seconds <br />";
			
		

Response

  • PHP
			
{ "access_token":"<Your access token>","expires_in":3600,"token_type":"bearer","scope":"a.user o.w.voipprofile" }
			
		


Scopes

Scopes limit the access to some parts of the APIs. If you try to access a specific resource without defining the scope in step 1, you will get a "403 Forbidden" error.

You can define one scope or several scopes (separated by commas).

Please refer to the Manager API Documentation for the list of scopes defined for its webservices.

Common errors

Parameters are missing

To get an authorization code you MUST provide 4 parameters as explained in step 1.

  • PHP
			
{
  "error": "invalid_request",
  "error_description": "Invalid request, parameters are missing"
}
			
		

Response type incorrect or missing

To get an authorization code, the response type parameter is required and MUST be set to "code".

  • PHP
			
{
   "error": "invalid_request",
   "error_description": "The response_type parameter value is missing or incorrect, the value MUST be set to "code""
}
			
		

State parameter is missing

If state parameter is not supplied, the request cannot be processed. This parameter is used against CSRF attacks.

  • PHP
			
{
   "error": "invalid_request",
   "error_description": "The state parameter is required"
}
			
		

Invalid client identifier

If your client identifier is incorrect, refer to your application settings to obtain the correct one.

  • PHP
			
{
   "error": "invalid_client",
   "error_description": "The client id supplied is invalid"
}