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 Element | Mandatory | Info |
---|---|---|
clientId | Yes | The client ID generated on creating a client in Deputy |
clientSecret | Yes | The client secret generated on creating a client in Deputy |
redirectUri | Yes | The redirect URI provided on creating a client in Deputy |
scope | Yes | This should always be passed as longlife_refresh_token |
hostname | Yes | The 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 Element | Info |
---|---|
accessToken | Access token to be used for API requests |
refreshToken | Refresh token to generate a new access token |
expiresIn | Expiry time in seconds, always 24 hours |
tokenType | type 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.
Updated about 1 year ago