How to Authenticate and Log Out

Overview

A PHP example on how to authenticate and logout of the v11 REST API using the /oauth2/token and /oauth2/logout POST endpoints.

Authenticating

The example below demonstrates how to authenticate to the REST v11 API. It is important to note that the oauth2 token arguments takes in several parameters that you should be aware of. The platform argument tends to cause confusion in that it is used to authenticate a user to a specific platform. Since Sugar only allows 1 user in the system at a time per platform, authenticating an integration script with a platform type of "base" will logout any current users in the system using those credentials. To work around this, your custom scripts should have a new platform type specified such as "custom_api" or any other static text you prefer. The client_id and client_secret parameters can be used for additional security based on client types. You can create your own client type in Admin > OAuth Keys. More information can be found in the /oauth2/token documentation. An example script is shown below:

  <?php

$instance_url = "http://{site_url}/rest/v11";
$username = "admin";
$password = "password";

//Login - POST /oauth2/token
$auth_url = $instance_url . "/oauth2/token";

$oauth2_token_arguments = array(
    "grant_type" => "password",
    //client id - default is sugar. 
    //It is recommended to create your own in Admin > OAuth Keys
    "client_id" => "sugar", 
    "client_secret" => "",
    "username" => $username,
    "password" => $password,
    //platform type - default is base.
    //It is recommend to change the platform to a custom name such as "custom_api" to avoid authentication conflicts.
    "platform" => "custom_api" 
);

$auth_request = curl_init($auth_url);
curl_setopt($auth_request, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0);
curl_setopt($auth_request, CURLOPT_HEADER, false);
curl_setopt($auth_request, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($auth_request, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($auth_request, CURLOPT_FOLLOWLOCATION, 0);
curl_setopt($auth_request, CURLOPT_HTTPHEADER, array(
    "Content-Type: application/json"
));

//convert arguments to json
$json_arguments = json_encode($oauth2_token_arguments);
curl_setopt($auth_request, CURLOPT_POSTFIELDS, $json_arguments);

//execute request
$oauth2_token_response = curl_exec($auth_request);

Request Payload

The data sent to the server is shown below:

  {
   "grant_type":"password",
   "client_id":"sugar",
   "client_secret":"",
   "username":"admin",
   "password":"password",
   "platform":"custom_api"
}

Response

The data received from the server is shown below:

  {
   "access_token":"c6d495c9-bb25-81d2-5f81-533ef6479f9b",
   "expires_in":3600,
   "token_type":"bearer",
   "scope":null,
   "refresh_token":"cbc40e67-12bc-4b56-a1d9-533ef62f2601",
   "refresh_expires_in":1209600,
   "download_token":"cc5d1a9f-6627-3349-96e5-533ef6b1a493"
}

Logout

To log out of a session, a request can be made to the  /oauth2/logout POST endpoint. More information can be found in the /oauth2/logout documentation. An example extending off of the above authentication example is shown below:

  //Logout - POST /oauth2/logout

$logout_url = $instance_url . "/oauth2/logout";

//decode oauth2 repsonse to get token
$oauth2_token_response_obj = json_decode($oauth2_token_response);
$oauth_token = $oauth2_token_response_obj->access_token;

$logout_request = curl_init($logout_url);
curl_setopt($logout_request, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0);
curl_setopt($logout_request, CURLOPT_HEADER, false);
curl_setopt($logout_request, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($logout_request, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($logout_request, CURLOPT_FOLLOWLOCATION, 0);
curl_setopt($logout_request, CURLOPT_HTTPHEADER, array(
    "Content-Type: application/json",
    "oauth-token: {$oauth_token}"
));

//set empty post fields
curl_setopt($logout_request, CURLOPT_POSTFIELDS, array());

//execute request
$oauth2_logout_response = curl_exec($logout_request);

Response

The data received from the server is shown below:

  {
    "success":true
}

Download

You can download the full API example here.