Using OAuth 2.0 for Installed Applications
AffinityLiveAccelo'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 AffinityLiveAccelo's API from an installed application
...
A user will be directed to visit an AffinityLive Accelo OAuth 2.0 URL with a set of query parameters. After authentication (handled by AffinityLiveAccelo) the user will be presented with a PIN and a QRCode. The user will be prompted to supply the PIN to the installed application.
...
Once the application has an access token, it may use this to access the AffinityLive 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.
| Code Block | ||
|---|---|---|
| ||
https://hq.api.accelo.com/oauth2/v0/authorize? scope=read(all)& response_type=code& client_id=34ad67fa2f@hq.affinityliveAccelo.com |
Please note that the above sample url should be encoded. For example purposes it was left in plain text.
...
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 | 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.
...
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 AffinityLiveAccelo's Resource endpoints by including it in either a _bearer_token query parameter or as a (preferred method) HTTP Authorization: Bearer header.
...