Getting Started With The Conversations API
Learn about how to authenticate for Khoros Marketing's Conversations API and troubleshoot.
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
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.
Updated 11 months ago