Overview
This document describes SalesHood’s API authentication process. At a high level, the process requires the client application using SalesHood’s APIs to request permission from the end user before performing any actions on their behalf.
Please contact SalesHood customer success for your company credentials which includes your client_id and client_secret.
OAuth Token Exchange
The user will be asked to authenticate themselves and if successful, an OAuth token will be provided. The OAuth token can then be used to get an access token.
Request
Endpoint: /public/oauth
| Parameter | Value | Required | Description |
|---|---|---|---|
| client_id | obtained from API configuration page | yes | Identifies the application |
| redirect_uri | a secure, absolute URI, for example https://example.com/oauthDemo | yes | User will be redirected here at the end of the authorization process. The value must belong to the set of values configured for this client id |
| state | any string | no | This value will be returned to the client as a parameter at the end of the authorization process |
Asynchronous Response
Endpoint: redirect_uri
If the request succeeded:
| Parameter | Value |
|---|---|
| oauth_token | the authorization code which the client must use in the Access Token Request step. Note that this code is only valid for 5 minutes |
| state | the value of the state initially passed in, if any |
| api_access_point | the base URI to be used in all subsequent calls both for access tokens and for API calls |
If the request failed:
| Parameter | Value |
|---|---|
| error | One of: INVALID_REQUEST – request is not well formed INVALID_CLIENT – client id is missing or invalid ACCESS_DENIED – user declined to grant access or doesn’t have the permission SERVER_ERROR – an internal server error occurred |
| error_description | Human readable text of why the request failed |
Access Token Request
In this step, the OAuth token is exchanged for an access token which can be used as an API key in SalesHood’s APIs. Access tokens have an expiration lifetime. Once an access token has expired, the client must request a new access token using the refresh token.
Note: Refresh tokens expire after 60 days of inactivity, i.e. the client can use the refresh token indefinitely, as long as it is being used at least once every 60 days, otherwise it expires automatically.
Request for Token
Endpoint: /oauth/token
| Parameter | Value | Required | Description |
|---|---|---|---|
| client_id | obtained from API configuration page | yes | Identifies the application |
| client_secret | obtained from API configuration page | yes | Authenticates the application |
| redirect_uri | must match the value used in the previous step | yes | The callback url |
| oauth_token | the authorization code obtained in the previous step | yes |
Example:
POST /oauth/token HTTP/1.1 Host: secure.saleshood.com Content-Type: application/x-www-form-urlencoded oauth_token=d5Q3HC7EGNH36SE3N& client_id=ABC& client_secret=03OuiSJYIVLYdIu& redirect_uri=https://example.com/oauthDemo&
Response for Token
| Parameter | Value |
|---|---|
| access_token | this can be used as an API key |
| expires_in | the lifetime of the access_token (in seconds) |
| refresh_token | this can be used to get a fresh access token. refresh_token expires after 60 days of inactivity (see note above) |
Example:
{ "access_token":"X", "expires_in":3600 "refresh_token":"X", }If the request failed:
| Parameter | Value |
|---|---|
| error | One of: INVALID_REQUEST – request is not well formed INVALID_CLIENT – client id is missing or invalid INVALID_OAUTH_TOKEN – oauth token is expired or not exists ACCESS_DENIED – user declined to grant access or doesn’t have the permission SERVER_ERROR – an internal server error occurred |
| error_description | Human readable text of why the request failed |
Refresh Request
Request to Refresh
Endpoint: /oauth/refresh
| Parameter | Value | Required | Description |
|---|---|---|---|
| client_id | obtained from API configuration page | yes | Identifies the application |
| client_secret | obtained from API configuration page | yes | Authenticates the application |
| refresh_token | the refresh token received during the previous step | yes |
Example:
POST /oauth/refresh HTTP/1.1 Host: secure.saleshood.com Content-Type: application/x-www-form-urlencoded refresh_token=X client_id=ABC& client_secret=X
Response to Refresh
If the request succeeded:
| Parameter | Value |
|---|---|
| access_token | this can be used as an API key |
| expires_in | the lifetime of the access token (in seconds) |
Example:
{ "access_token":"X", "expires_in":3600 }If the request failed:
| Parameter | Value |
|---|---|
| error | One of:INVALID_CLIENT – client id is missing or invalid INVALID_REFRESH_TOKEN – refresh token is missing, invalid, or expired SERVER_ERROR – an internal server error occurred |
| error_description | Human readable text of why the request failed |
Need further assistance? Please reach out to victoria.riley@saleshood.com for anything API related.
Leave A Comment?
You must be logged in to post a comment.