Using OAuth 2.0 for Service Applications
AffinityLiveAccelo'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 AffinityLive Accelo deployment and should be server-to-server.
This document describes how to use OAuth 2.0 when accessing AffinityLiveAccelo's API from a service application
...
The application will request an access token directly from the AffinityLive 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 AffinityLive 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 AffinityLive 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:
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:
|
Here is what a request may look like, where the client id and secret are encoded using base-64.
...
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.
...
Once the application has obtained an access token, it can use it to access AffinityLiveAccelo's Resource endpoints by including it in either a _bearer_token query parameter or as a (preferred method) HTTP Authorization: Bearer header.
...
| Code Block | ||
|---|---|---|
| ||
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 AffinityLive Accelo user on our al-devel forum.
| Code Block | ||
|---|---|---|
| ||
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
...