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.