Using OAuth 2.0 for Service Applications

Accelo's OAuth 2.0 endpoints support service applications. These applications do not require the permission of the end user and are executed from the owner of the API application with full permissions.

Service applications should only be used when data needs to be accessed or modified by an individual or application outside of an Accelo deployment and should be server-to-server.

This document describes how to use OAuth 2.0 when accessing Accelo's API from a service application

Overview

The application will request an access token directly from the Accelo OAuth 2.0 token endpoint in exchange for its client credentials as an authorization grant.

Once the application has an access token, it may use this to access the Accelo API.

Gaining Access

When accessing the token endpoint it is recommended you authenticate yourself using HTTP Basic Authentication using the client_id and client_secret as username and password. The Accelo OAuth 2.0 does support sending the client_id and client_secret as query parameters as a last option.

The table below contains the token parameters.

Parameter

Values

Description

grant_type

client_credentials

This must be client_credentials.

scope

The permissions your application requests.

A scope is used to convey what permissions your application requires when requesting permission from the end-user. Current available scopes are:

read(all) - Read only access to all data the user owns or has access to including personal information, and
write(all) - Read and write access to all data the user owns or has access to including personal information.
read({resource}) - Read only access to data related to the {resource} object.
write({resource}) - Read and write access to data related to the {resource} object.

Scope resources can be any of our endpoints. For example, companies, contacts or issues. The scope can be concatenated and delimited by a comma. For example:

read(all),write(companies,contacts) - read all information and write to only companies and contacts.
write(contacts,issues) - Read and write access to contact and issue data.

The request must authenticate using HTTP basic. The format is client_id:client_secret. Use your applications client id as the username and its client secret as the password encoded with base-64 encoding.

For example,

POST /oauth2/v0/token HTTP/1.1
Host: hq.api.accelo.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic NzY1NzVmYzJAaHEuYWNjZWxvLmNvbTpSYWp3MGFhc0g1YUU1X2lDbTc=
  
grant_type=client_credentials

For example, using curl expecting a JSON response
For this example client_id and client_secret are not encoded.

curl \
-u {client_id}:{client_secret} \
--data "grant_type=client_credentials" \
"https://{deployment}.api.accelo.com/oauth2/v0/token.json"

Upon a successful request, the response contains the following fields:

Response	Values	Description
access_token	string representing an access.	Credential used to access Accelo's protected resources
token_type	bearer	The type of token returned.
expires_in	Seconds until the token expires.	Indicates the time remaining before the token expires and becomes invalid.

A refresh token is not presented for service applications. If a token expires, a service application should query the token endpoint again as done above.

Accessing the resource

Once the application has obtained an access token, it can use it to access Accelo's Resource endpoints by including it in either a _bearer_token query parameter or as a (preferred method) HTTP Authorization: Bearer header.

Sample accessing a company resource using access token in query:

GET https://hq.api.accelo.com/api/v0/companies/1?_bearer_token=frLA0s1m_D

Sample using the preferred Authorization header method:

GET /public_api/v0/companies/1 HTTP/1.1
Host: hq.api.accelo.com
Authorization: Bearer frLA0s1m_D

Examples

PHP

The following snippet was kindly provided by Chris Williams, an Accelo user on our forum.

public function authorize(){
	/* 
	Description: make the authorization request to the api as a service application
	return: json decoded array
	*/
		$curl = curl_init();
		curl_setopt_array($curl, array(
		      CURLOPT_RETURNTRANSFER => 1,
		      CURLOPT_URL => 'https://'.$this->getDeploymentName().'.api.accelo.com/oauth2/v0/token',
		      CURLOPT_POST => 1,
		      CURLOPT_POSTFIELDS => array(
		        response_type => 'code',
		          grant_type => 'client_credentials',
		          client_id => $this->getClientId(),
		          client_secret => $this->getClientSecret()
		          
		      )
		));
		  // Send the request & save response to $resp
		$resp = curl_exec($curl);
		  // Close request to clear up some resources
		curl_close($curl);

		$resp = json_decode($resp);

		if($resp->error=='invalid_client'){
			//Couldn't authenticate - Try Again
			return false;
		}

		return $resp;
	}

References and additional reading

APIs

Service Applications