API Authentication

For all API documentation go here: https://support.saleshood.com/2019/09/user-reporting-api/

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

ParameterValueRequiredDescription
client_idobtained from API configuration pageyesIdentifies the application
redirect_uria secure, absolute URI, for example https://example.com/oauthDemoyesUser 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
stateany stringnoThis value will be returned to the client as a parameter at the end of the authorization process

Example: 

https://secure.saleshood.com/public/oauth?client_id=ABC&redirect_uri=https://example.com/oathDemo

(replace secure subdomain with your company subdomain. E.g. saleshood, domo, alteryx)

Asynchronous Response

Endpoint: redirect_uri

If the request succeeded:

ParameterValue
oauth_tokenthe authorization code which the client must use in the Access Token Request step. Note that this code is only valid for 5 minutes
statethe value of the state initially passed in, if any
api_access_pointthe base URI to be used in all subsequent calls both for access tokens and for API calls

If the request failed:

ParameterValue
errorOne 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_descriptionHuman 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

Endpoint: /oauth/token

ParameterValueRequiredDescription
client_idobtained from API configuration pageyesIdentifies the application
client_secretobtained from API configuration pageyesAuthenticates the application
redirect_urimust match the value used in the previous stepyesThe callback url
oauth_tokenthe authorization code obtained in the previous stepyes

Example:

POST /oauth/token HTTP/1.1 Host: secure.saleshood.com Content-Type: application/x-www-form-urlencoded oauth_token=X client_id=ABC& client_secret=X redirect_uri=https://example.com/oauthDemo&

Response

ParameterValue
access_tokenthis can be used as an API key
expires_inthe lifetime of the access_token (in seconds)
refresh_tokenthis 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:

ParameterValue
errorOne 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_descriptionHuman readable text of why the request failed

Refresh Request

At any point in the future, the client can use the refresh token to receive a new access token. Client application must be prepared to deal with an invalid refresh_token response, i.e. perform OAuth process to get a new refresh_token.

Request

Endpoint: /oauth/refresh

ParameterValueRequiredDescription
client_idobtained from API configuration pageyesIdentifies the application
client_secretobtained from API configuration pageyesAuthenticates the application
refresh_tokenthe refresh token received during the previous stepyes

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

If the request succeeded:

ParameterValue
access_tokenthis can be used as an API key
expires_inthe lifetime of the access token (in seconds)

Example:

{  "access_token":"X", "expires_in":3600 }

If the request failed:

ParameterValue
errorOne 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_descriptionHuman readable text of why the request failed

Was this article helpful?

Leave A Comment?

You must be logged in to post a comment.