The Automation Framework authenticates calls to the Bot API v3 by JSON Web Token (JWT). JWT is an industry-standard authentication mechanism. See jwt.io for supported languages and platforms. The JWT consists of a header, a payload, and a signature.

📘

Note

Requests to Care v1 and v2 APIs use Basic authentication and a different API URL. Only requests to the Bot API v3 use JWT authentication.

A token looks something like this.

eyJhbGciOiJIUzUxMiJ9.eyJjb21wYW55S2V5Ijoic2NvdHRpc2hwb3dlcmRldiIsInVzZXJOYW1lIjoiQVBJIFN5c3RlbSBVc2VyIiwiYXdzUmVnaW9uIjoidXMtd2VzdC0yIiwiZXhwIjoxNTQyNTc3ODkwfQ.uPG-r6KF5kVI5zGoRFYw7zNpp3CuqRURUx74cUNAfOQTIup5RJOBockGng1rioCspAcOwGfFZeAdZEp4998k9A

In your calls to the Bot API v3, you will pass the token in the Authorization header using the format:
Bearer [TOKEN]

cURL Example
curl https://[API GATEWAY DOMAIN]/bots/v3/respond \
  --data @sample-response.json \
-H "Content-type: application/json; charset=utf-8" \
-H "Authorization: Bearer [TOKEN]"

Generate a JWT token

Generate a JWT token with a POST call to /api/v2/tokens/khorosapi/ownerId/{ownerId} where:

• ownerId is the owner of the token. This is the appId provided in the registration payload.
• <serverUrl> is the URL to your Khoros Care environment (e.g., <something>.response.lithium.com)

🚧

Important

The request to generate the JWT requires Basic authentication using a Khoros Care user account with the Bot API role. In your production environment, we recommend using a service account user with an email address not tied to a specific person.

The token expires after the date (expiresAtMillis) present in the response (90 days from when it was issued) and you must refresh prior to this expiration for uninterrupted service. This endpoint is intended for token creation only. *Once the token is generated, a second call to this endpoint will result in a 409.

👍

Tip

You may check if a token for the bot already exists via a GET request to /api/v2/tokens/khorosapi/ownerId/{ownerId}.

curl -u username:password -XPOST \
https://your.response.instance.com/api/v2/tokens/khorosapi/ownerId/[OWNER ID] \

Check whether a JWT exists for a bot

The first POST call to /api/v2/tokens/khorosapi/ownerId/{ownerId} generates a JWT. A second call to this endpoint results in a 409 error. Make a GET call to /api/v2/tokens/khorosapi/ownerId/{ownerId} to check whether a token for the bot already exists. This may be helpful when troubleshooting a 409 response.

curl -u username:password -XGET \
'https://your.response.instance.com/api/v2/tokens/khorosapi/ownerId/[OWNER ID]' \

Refresh the JWT

👍

Best Practice

We strongly recommend automating the JWT refresh so that bots do not make calls with a stale token.

You may refresh the JWT by making a PUT call to /bot/v3/tokens/appId/{appId}.

curl -X PUT \
  https://[API GATEWAY DOMAIN]/bots/v3/tokens/appId/{appId} \
  -H "Content-type: application/json; charset=utf-8" \
  -H "Authorization: Bearer [TOKEN TO BE REFRESHED]"

The call returns a new token with a new expiration stamp (expiresAtMillis). We strongly recommend automating the JWT refresh so that bots do not make calls with a stale token. The token may be refreshed at any time prior to expiration. Once an old token is submitted for refresh, it will remain valid for a grace period of 10 minutes. Once the 10-minute window passes, only the new token returned by the call will be valid.

Invalidate the JWT

Invalidate the JWT with a DELETE call to /bots/v3/tokens/appId/{appId}.

When you call the invalidation endpoint (DELETE) all the tokens associated with the given appId will be invalidated. This endpoint is intended for deleting compromised tokens and is not subject to a 10 minute grace period as is with a refresh. There may be a small degree of latency while our systems update. Afterwards, you will have to start over by creating a token with /bots/v3/tokens/khorosapi/ownerId/{ownerId} .

curl -X DELETE \
  https://[API GATEWAY DOMAIN]/bots/v3/tokens/appId/{appID} \
  -H "Authorization: Bearer [TOKEN]"