Guides

Using Oauth 2.0

Suggest Edits

For those applications which are designed to be used by hundreds if not thousands of Deputy users, the Oauth 2.0 flow is the method to obtain an API token.

Setup

The first thing you will need to do as a developer is to obtain a Client ID and Secret. These in combination with each other will identify your application to Deputy when a user is trying to grant access.

You will need to sign up for a Deputy Trial. This trial account can be used to set up a new integration as well as for ongoing platform testing. By default, the trial period lasts for seven days but can be greatly extended by contacting Deputy API support.

Once you have signed up for a trial and completed the initial setup, you will have your own Deputy installation ready for development. You will note that it has an installation name and a geographic location.

For example, https://simonssambos.au.deputy.com is an installation called simonssambos and is present in the Australian geographic region. There are four possible regions for a Deputy installation currently

  • AU (Australia)
  • EU (Europe)
  • UK (United Kingdom)
  • US (United States)

It is important to know this as you should not make any assumptions about where a users installation region may be.

Setting up a new Client ID

Once you have signed up for a trial you can set up a new Client ID for the Deputy API in the user area of Deputy known as Once.

URL
https://once.deputy.com/my/oauth_clients

Once you are on the page having logged in click New Oauth Client

A form will then be displayed. This is where you capture important information about your application including your app name and description. It is important to know that the description listed here will be shown to all users attempting to authorise your app so please keep this in mind.

When you have filled all this information out, click Save this Oauth client

You will then see a summary of your app record including the Client Id and Client Secret.

Obtaining a Token

Once you have setup a new Client ID the next step is to implement a process to obtain a token. This is made up of three parts

  1. Sending a request to Deputy for authentication and then retrieving an access code.
  2. Using that access code to retrieve an access token and refresh token
  3. Using the refresh token in the future to obtain a new access token.

🚧

Deputy Access Token

Deputy access tokens currently last for twenty four hours. After which you will need to obtain a new token by using the latest refresh token.

Sending a request to Deputy for authentication and retrieving an access code.

The first step in this process is to use your client id in a request to the Deputy Once URL. This will begin the process of allowing a Deputy user to authenticate your application for their installation.

The structure of this call is:

https://once.deputy.com/my/oauth/login

with the following query parameters:

  • client_id: - This is your client id that has been setup in Deputy
  • redirect_uri: This is the redirect URL you setup when adding your new client app to Deputy
  • response_type: This is always set to code to ensure you are using the code based Oauth 2.0 flow
  • scope: This is always longlife_refresh_token to ensure that you can retrieve access tokens in the future.

For example if your client id is 1234 and the redirect URL which has been set is http://localhost then the request would be

https://once.deputy.com/my/oauth/login?client_id=1234&redirect_uri=http://localhost&response_type=code&scope=longlife_refresh_token

Once this is complete a client will be redirected to the URL that you setup for your client id in Deputy. It will include an access code.

For example https://localhost?code=XXXXXXXXX
f

🚧

Code

This code is not an access token and cannot be used to connect directly to the Deputy API. It is instead used to obtain an access token in the next step of the authentication process.

Oauth2 Client for a single install

It is possible for you to add an Oauth2 client which will only work for a specific install. To do this instead of using the Once url, visit *https://{install}.{geo}.deputy.com/exec/devapp/oauth_clients.

Exchanging the Code for an Access Token

Once you have obtained a code from the first request, you then need to exchange this code for an access token. This must be completed within ten minutes else the code will expire .

To exchange the code for an access token you need to do a POST request to https://once.deputy.com/my/oauth/access_token

🚧

X-WWW-FORM-URLENCODED

This must be sent in a application/x-www-form-urlencoded format else you will get an error saying 'We did not detect 'code' in POST call

The content of the POST must include the following data:

  • client_id: Your applications client id.
  • client_secret: The client secret of your application
  • redirect_uri: The redirect URL set when adding the client application to Deputy.
  • grant_type: This is always authorization_code.
  • code: The code you retrieved from the redirected URL in the previous request.
  • scope: This is always longlife_refresh_token to ensure that your application is able to retrieve another access token in the future.

Once the application has performed this request you will receive a response like the below

{"access_token":"aa50fa64b2b9824135xxxxxxxxxxxxx",
"expires_in":86400,
"scope":"longlife_refresh_token",
"endpoint": {install}.au.deputy.com",
"refresh_token":"ef5caf9e931a0f1ecxxxxxxxxxx"}
  • access_token: This is the access token that can be used to access the Deputy API directly
  • expires_in: The remaining time before this access token will expire and when your app will need to retrieve a new one
  • scope: The scope included for this token
  • endpoint: The endpoint the token is related to. If a client has multiple Deputy installs, the token will only work with the one they have selected as part of the authentication flow. In other words, the relationship between an access token and Deputy install is one-to-one. You will need to store this as it will be required for the API requests into the user's Deputy install.
  • refresh_token: This token can be used to obtain another access token in the future without the user having to go through the authentication process again.

Renewing an Access Token

Once the access token has expired (one indication of this is starting to see 401 unauthorised errors) you will need to use the refresh token to obtain a new access token.

To do this your application will need to make a POST request to https://{usersinstall}.{geo}.deputy.com/oauth/access_token

The following content needs to be included in the POST request:

  • client_id: The client id of the application
  • client_secret: The client secret of your application
  • redirect_uri: The redirect URL that has been set for your application
  • grant_type: Always refresh_token
  • refresh_token:. The refresh token your application saved from the previous request. If you do not have this refresh token you will need the user to go through the full authentication process again
  • scope: Always longlife_refresh_token

🚧

Refresh Token Expiry

Using a refresh token to renew an access token will invalidate it. When the new access token is returned, a new refresh token will also be included that should be stored for use the next time an access token is required. As long as this process is maintained, you are able to retrieve new refresh and access tokens forever.

Sending the token with API requests

Once you have obtained the access token your application will need to include it in all API requests to obtain data from or post data to the Deputy install. To do this include a header with all requests

  • Authorization: Bearer {Access Token}

Validating an access token

Once an access token has been retrieved from the Deputy Oauth service, it is a good idea to validate it before moving on. An easy way to do this is to make an API request to the Who am i endpoint which will return information about the owner of the access token.

This can be done by sending a GET request to https://{deputyinstall}.{geo}.deputy.com/api/v1/me

❗️

User consent removed

A user can at any time remove the consent for your application from their Deputy install. If a user removes consent, they will be required to perform the full authentication process again before being able to use your application.

Updated 7 months ago