This tutorial covers how you can start using Khoros Marketing’s Conversations API. The first step is authentication. We use 3-legged OAuth 2.0 for authentication.

The overall flow will be to first gather your credentials, then call /authorize, pass received information into /grant, and again finally to /token. This last call will return an accessToken which will be used to authenticate you for all subsequent calls to the Khoros Marketing API.

Prerequisites

Before we begin, there you will need to collect your specific credentials. Both for your user and your API access clientId and clientSecret:

• clientId - Your person API key for Khoros Marketing.
• clientSecret - Your personal API secret for Khoros Marketing.
• loginEmail - the email address you use to log into Khoros Marketing.
• loginPassword - the password you use to log into Khoros Marketing.

Developer Auth Flow

Obtaining a JWT API Access Token

You can now acquire an API Access Token directly from within the Profile Settings area of Khoros Marketing. We have created a detailed guide on how to acquire an API Access Token unique to your user login in Atlas.

USING YOUR ACCESSTOKEN

Now that you have your accessToken, you can now call our /me endpoint to get access your user and company.

curl -XGET \
   https://api.spredfast.com/v2/me \
   -H 'Authorization: Bearer <accessToken>'  

{
   "data": {
     "sfEntityType": "User",
     "email": "[email protected]",
     "companies": [
       {
         "sfEntityType": "AvailableCompany",
         "id": "123",
         "name": "Your Company",
         "environment": "Production"
       }
     ]
   },
   "status": {
     "succeeded": true
   }
}

Authentication Token Notes

Our authentication method is designed for long term application and server usage. Therefore, a bearer token from this method is valid for 2 years and persists across password changes. The token is all that is needed to make API calls on your behalf; be certain it is saved in a secure location. A token can be revoked at any time by the authenticating user in Profile Settings -> Notifications.

Troubleshooting

If you encounter any issues, here are a few troubleshooting steps you can try.

ERROR: USER CREDENTIALS

If you send a bad userEmail or userPassword, you will receive an HTML page saying the following:

Incorrect Email or Password

ERROR: INCORRECT CLIENTID/SECRET

If your clientId is incorrect, you will receive an HTML page saying:

An unrecognized application has requested access to your Khoros Marketing Account. It was not possible to process this request because the application identifier provided (client_id = 588qyu7qpjabcdef8hijkn6qonetwo) is not valid. Please contact your application administrator to resolve the issue.

If your clientSecret is incorrect, you will not receive an error until the /token step, at which point you will get a 500 SERVER ERROR response.

BAD URL PATH

If you are using a v1 endpoint and get the following when accessing an API endpoint:

<h1>586 Service Not Found</h1>

You are likely attempting to call an API that doesn’t exist. Please note that the environment part of our URL endpoints are case sensitive, thus https://api.spredfast.com/Production/v1 is correct, but https://api.spredfast.com/production/v1 is not. A list of valid environments are:

https://api.spredfast.com/Production
https://api.spredfast.com/VPC1
https://api.spredfast.com/APP3

DEVELOPER INACTIVE

If you should ever get the following response: <h1>Developer Inactive</h1> error, then your accessToken has likely expired.