- style
Installed Applications
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
Contents
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:
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:
|
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