Using OAuth 2.0 for Installed Applications

Accelo's OAuth 2.0 endpoints support installed applications, like those installed on mobile and PC devices. Currently the process assumes the user has access to a browser and that the client cannot keep secrets.

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

Overview

A user will be directed to visit an Accelo OAuth 2.0 URL with a set of query parameters. After authentication (handled by Accelo) the user will be presented with a PIN and a QRCode. The user will be prompted to supply the PIN to the installed application.

The QRCode contains the user's username, deployment and PIN in the following format:

qr_text = deployment || ';' || username || ';' || pin

where deployment and username are specific to the end-user and || is concatenation.

The installed application can then exchange the PIN for an access and refresh token by presenting its client_id and client_secret along with the PIN.

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

Forming the URL

The OAuth 2.0 Authorization URL is oauth2/v0/authorize where SSL is required and the host is the deployment for the user requesting the access (not the installed application's deployment host).

Below is a table of accepted query parameters. The optional fields are underlined.

Parameter

Values

Description

client_id

The applications client id obtained from the API Control Panel.

Indicates what API application is making the request. It is a unique string allocated to your application, which can be used across multiple deployments. For example: 34ad67fa2f@hq.Accelo.com

response_type

code

This value must be code for installed applications.

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.

Example URL.

https://hq.api.accelo.com/oauth2/v0/authorize?
scope=read(all)&
response_type=code&
client_id=34ad67fa2f@hq.Accelo.com

Please note that the above sample url should be encoded. For example purposes it was left in plain text.

Handling the response

The user will be presented with a QRCode and PIN, they will be directed to return to your application with the pin if they wish to allow access. These pins expire in 300 seconds (5 minutes).

Sample of grant request given to end-user.

QR codes disabled

Currently, QR codes are disabled. The user must manually enter the pin

Once you have received an authorization code from the authorization endpoint or user, you can exchange it for an access and refresh token.

The OAuth 2.0 access token URL is oauth2/v0/token where SSL is required and the host is the deployment for the user requesting the access (not the web applications deployment host).

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	authorization_code	This is required when requesting access using an authorization grant. Note. You can send refresh_token to indicate that you are using a refresh token. In this situation, you should also send the refresh_token.
code	The code obtained during the authorization request.	This code was obtained during the authorization request and is used to obtain an access token.
redirect_uri	The redirect uri passed in the authorization request.	This must be the same as the uri passed during the authorization, failure to do so will result in an invalid_grant error.

Here is what a request may look like, where the client id and secret are encoded using base-64.

POST /oauth2/v0/token HTTP/1.1
Host: hq.api.accelo.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic {client_id}:{client_secret}
 
code=frLA0s1m_D&
 
grant_type=authorization_code

For example, using curl with a JSON response

curl \
-u {client_id}:{client_secret} \
--data "code={code}&grant_type=authorization_code" \
"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
refresh_token	string representing an authorization grant	A refresh token can be used to obtain a new access token. It is similar to an authorization code in that it is a credential used to obtain an access token.
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. Upon a token expiring you can use therefresh_token to request a new access token.

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 /api/v0/companies/1 HTTP/1.1
Host: hq.api.accelo.com
Authorization: Bearer frLA0s1m_D

References and additional reading

APIs