The "Hello World" of Deputy

This guide will take you through a basic connection to Deputy. In this guide, you will be retrieving information about the user related to your access token. It will take you through setting up a permanent token in your Deputy install for early development purposes and connecting to the Who Am I endpoint.

Deputy Install

Developers wanting to build with Deputy can easily set up a trial account at https:///www.deputy.com. Once you've set up your account reach out to the API support team ([email protected]) who can extend the account beyond its initial trial period for development purposes.

You will note once you've signed up that your Deputy install will have a specific URL in the structure of https://{installname}.{geo}.deputy.com - This is the same URL that will be the base API url for this particular install.

eg: https://simonssambos.au.deputy.com

Authentication

To get going quickly you can set up a permanent token in your Deputy install. This token will grant you API access to your own install allowing you to quickly see how the API works.

To setup a permanent token open the following URL. https://{installname}.{geo}.deputy.com/exec/devapp/oauth_clients.

Click the New OAuth Client button - Even though we are generating a permanent token, a client must still be added to the Deputy install.

Once you have clicked the button, the New OAuth Client form will display.

You will need to enter some details here:
Name - This is the name the client will appear as in the Deputy install backend
Description - This the description that will appear in Deputy client installs when the application is added
Logo Url - If you would like Deputy to provide a custom logo URL during the OAuth process, you can define the location of that image here. For this example we will leave it blank.
Redirect Uri - The URL where the OAuth process will return a user once authentication is complete. Even though it's not used with permanent tokens, it's a mandatory field so in this example we can enter http://localhost.

Once you have finished entering the information click the Save this OAuth Client button.

You will then reach a summary page of the new client which has been added to the Deputy install.

To generate a new permanent token for this install click the Get an Access Token button.

Once you click the button a modal dialog will appear displaying the permanent token.

❗️

IMPORTANT

The permanent token will only be displayed in this modal dialog once. It is not possible to see the permanent token again once this dialog is closed. Ensure you save it somewhere secure before clicking OK.

Connecting to the API with the permanent token

Once you've grabbed the permanent token, there are generally three ways you can connect to the API to see how it works.

Directly from the docs - As part of the Deputy API docs we allow developers to connect to the API directly if you already have a valid token.
POSTMAN - POSTMAN is a widely used API testing tool which can make it easy to try APIs out before getting into your own code
Your own code - You can of course build an example in your own code to see how it works.

Below we will focus on using the API directly from the docs.

Using the API tools on Deputy Docs

As part of the Deputy API documentation we offer the ability for developers who already have a valid token, to connect and try out the API without having to touch any code or tools.

For this example we are going to use the Who Am I API which can be found here. Who Am I

Once that page is open you will see the API reference docs for the Who Am I API endpoint. On the right hand side you will see the Try It feature.

There are three key pieces of information you need to add before you can try the API:

deputyinstall - This is the name of your deputy business based on its URL, so for example if your URL is https://simonssambos.au.deputy.com then the deputyinstall is simonssambos.
geo - This is the geographic location of the Deputy install. Typically AU, UK or NA. This also comes from the Deputy install URL.
token - This is the permanent token you generated previously in this guide.

Example

Once everything is setup, click the Try It! button to connect to the API. You should then get a response from the Who Am I endpoint with information about the affiliated user.

You've successfully connected to the Deputy API!