Calling APIs on behalf of a Deputy embedded account

Generating an access token

A common case for an embedded partner is calling business specific APIs on behalf of a Deputy business. These APIs require an access token as an authorisation header.

For example:

  • Calling our location API to add locations to an account
  • Calling our people API to add users to an account, and change their details.
  • Calling our timesheet API to pull over time and attendance information.

To do this, you first must set up a client on the account. Setting up a client will give you the Client ID and Client Secret that will need to be used in the payload to generate the token.

Getting an access token

Given the hostname of a install that has been created via our provisioning API, you can call the token endpoint.

πŸ“˜

Bearer Token

You will need to pass in a bearer token (created here https://dash.readme.com/project/deputy-docs/v1.0/docs/provisioning-api-security-overview) in order to access this API.

cURL 'https://api.usw2.deputy.com/connect/v1/partner/{partnername}/auth/token'

{partnername} is the name we assign to your embedded integration.

{  
    "clientId":"{clientId}",  
    "clientSecret":"{secret}",  
    "redirectUri":"{redirect URL}",  
    "scope":"longlife_refresh_token",  
    "hostname":"{hostname}"  
}

Note: The clientID and secret here will be given by the Deputy team.

Data Elements

Data ElementMandatoryInfo
clientIdYesThe client ID generated on creating a client in Deputy
clientSecretYesThe client secret generated on creating a client in Deputy
redirectUriYesThe redirect URI provided on creating a client in Deputy
scopeYesThis should always be passed as longlife_refresh_token
hostnameYesThe URL of the created Deputy account.

To this request the response would be:

{
    "success": true,
    "data": {
        "accessToken": "access token",
        "refreshToken": "refresh token",
        "expiresIn": "86400",
        "tokenType": "OAuth"
    }
}

Which will include an access token to pass with your API requests, in addition to a refresh token.

Data Elements Returned

data

Data ElementInfo
accessTokenAccess token to be used for API requests
refreshTokenRefresh token to generate a new access token
expiresInExpiry time in seconds, always 24 hours
tokenTypetype of access token, only informative purpose

Renewing Access Token

Renewing an access token can be done using the refresh token obtained in the previous API call. Please refer to the API documentation here on how to renew.