Please enable JavaScript to view this site.

Navigation: Advanced topics > Programming topics > REST API Connections

Custom REST API Authentication

Scroll Prev Next More

The Custom authentication code runs each time when the application is going to perform a REST API request. The request description is passed to the code in the request parameter in the form of HttpRequest object. The app expects that the custom code will modify the request and add some authentication information to it.

 

rect_api_custom_connection

 

Parameters passed to the custom authentication code:

 

connection

RestConnection object. Represents the connection itself. Can be used to run requests against it.

mode

String. Has either "data" or "validate" value. See the OAUTH 2.0 section below

request

HttpRequest object. Description of the request to the REST API the app is about to make. It expects you to add authentication data to it.

code

String. Only used with mode="validation". See the OAUTH 2.0 section below

 

The process of PHPRunner-created app accessing a REST API can be described by this wokflow:

 

Create request object

Add authentication info to the request object. Here goes the Custom Authentication code

Send request to the API and receive response

Parse and process the response

Show data to the user

 

 

In basic cases you only need to add one or two parameters to the request

OAUTH 2.0

 

When OAUTH 2.0 process with the user logging into the API provider site is used, a multiple step authentication must be performed.

When accessing the API resource for the first time, the app must send the user to the API provider site. Your code should use setAuthorizationRequest function to signal about it.

 

// create authorization request
$authRequest = new HttpRequest( $authUrl );
...
// send authorization request to the application
$connection->setAuthorizationRequest( $authRequest );
// don't do anything else
return true;

 

 

After the user logs in on the API provider's site, the API sends back authorization code to the application. The application must validate the code and receive the access token

When using custom authentication, the custom code is called with mode parameter set to "validation" and code parameter has the code to validate.

 

if( $mode == "validate" ) {
  // create validation request
$validateRequest = new HttpRequest( $tokenUrl, "POST" );
  ...
// run validation request and parse result
$oauthToken = $connection->requestOauthToken( $validateRequest );
 
// save access token
$connection->setOauthToken( $oauthToken );
 
// don't do anything else for now
  return true;
}          

 

After successful validation the code should save the received access token. When called next time, the code should retrieve the saved access token and add it to the request.

 

$oauthToken = $connection->getOauthToken();
$request->headers["Authorization"] = "Bearer " . $oauthToken["access_token"];

 

Created with Help+Manual 7 and styled with Premium Pack Version 3 © by EC Software