Authentication

To make API requests you will need an Authentication Token. Authentication Tokens are temporary "security codes" (similar to session cookies) that allow the system to identify who you are, and that you are authorized to make changes in an account.

An authentication token can be generated two ways:

  • By submitting a username, password and account name pair
  • By submitting an API Key

Either of the above submissions will generate a temporary authentication token. You can then use the temporary token for the remainder of your API requests, whether they be in an automated script or in a test tool you are using.

The expiration of authentication tokens is one day, though this may vary depending on the system in use as it is configurable.

Usernames and Passwords are great for people, but sometimes people need to change their passwords (either because they lose them or they've been compromised). When this happens, it is typically a pain to go around to all your software programs and also change passwords. As a best practice, keep your username/password for use when administering your account and use API Keys when connecting third party software to the platform.

   

  • Guard your API Key with care! While authentication tokens expire, API keys do not.

You can retrieve your API key by making an HTTP GET request to the api_key entity:

GET https://c-api.conversanthq.com/v1/accounts/{AccountID}/api_key

To try this with CURL, you can type:

curl -X GET https://c-api.conversanthq.com/v1/accounts/{AccountID}/api_key -H "Content-Type:application/json" -H "X-Auth-Token: 555555c8d6f213098729999999999999"

You can generate an Authentication Token using your API Key. To do this, make an HTTP PUT request to the following URL, and include a JSON payload with the key:

PUT https://c-api.conversanthq.com/v1/api_auth
{"data": { "api_key" : "YOUR_API_KEY_HERE" }}

 

To try this with CURL, you can type:

curl -X PUT https://c-api.conversantgq.com/v1/api_auth -H "Content-Type:application/json" -d '{ "data" : { "api_key" : "YOUR_API_KEY_HERE" }}'

 

You will be returned a JSON response that looks like:

{"auth_token":"555555c8d6f213098729999999999999","status":"success","data":{"account_id":"55555514def94f7ce08cf3e1a999999"}}

You can generate an Authentication Token using a username/password. To do this, make an HTTP PUT request to the following URL, and include a JSON payload with the key:

PUT https://c-api.conversanthq.com/v1/user_auth
{ "data" : { "credentials" : "123456789012345678901234567890", "account_realm" : "YOUR.REALM.COM" }, "verb" : "PUT"}
Icon

Replace the "credentials" section above with the md5 hash of your username:password  (again, that's username COLON password).

To get an md5 of your hash you can use the following website: http://www.danstools.com/md5-hash-generator/

 

To try this with CURL, you can type:

curl -X PUT https://c-api.conversanthq.com/v1/user_auth -H "Content-Type:application/json" -d '{ "data" : { "credentials" : "123456789012345678901234567890", "account_realm" : "YOUR.REALM.COM" } }'

 

You will be returned a JSON response that looks like:

{"auth_token":"555555c8d6f213098729999999999999","status":"success","data":{"account_id":"55555514def94f7ce08cf3e1a999999"}}

 

On all subsequent requests past this point, include an HTTP header of:

X-Auth-Token: 555555c8d6f213098729999999999999

where 555555c8d6f213098729999999999999 is the auth_token that was returned in the first CURL command. This is how you authenticate your subsequent API calls.