Using a Permanent Token

A permanent token is an option best suited to those building a custom application for one or two Deputy installs or for an internal system connection of the Deputy customer.

While it may seem an easier process than the Oauth 2.0 flow, the administration work required to retrieve the token generally makes it unsuitable for commercial applications which have an aim of gaining hundreds of users.

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 admin area of your Deputy installation. Although with permanent tokens the Client ID is not used, this is still a required step before obtaining a permanent token. Follow along with the below video to do this.

URL

The URL to reach the Oauth area of a specific install is https://{install}.{geo}.deputy.com/exec/devapp/oauth_clients

Adding an Oauth client to this URL is for the single Deputy install only and it will not work on other installations. To have an Oauth client which works on all installs please follow Using Oauth 2.0

Getting a permanent token

Once you have added the Client ID, you can obtain a permanent token by clicking the Get an Access Token button on the Client ID page

❗️

Saving the permanent token

The permanent token which is generated is only displayed once during the modal dialog. You will not be able to find it again without generating a new one. Ensure that you save it in a safe place before closing the dialog.

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 a permanent 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