Custom Authentication for Live Chat
Updated
Custom Authentication enables you to securely identify authenticated users in Sprinklr Live Chat without exposing personal information, such as a user's name or email address, in client-side code.
Instead of passing user details directly, your application can pass secure identifiers or tokens. Sprinklr uses these identifiers to authenticate the user and retrieve the corresponding user information.
How it Works
With this method, your application passes one or more reference tokens instead of exposing customer information in the browser. The tokens are accompanied by a signed chat user signature. Sprinklr Live Chat uses the tokens to retrieve the corresponding customer details from the brand’s configured API.
At a high level:
Brand’s application passes the reference token(s) and signed hash to Live Chat.
Live Chat uses the configured API to retrieve the associated customer information.
The retrieved information is associated with the Live Chat user.
Note: Alternatively, brands can choose to pass a Sprinklr generated JWT token. In this case the flow will be as follows:
Authorize API request
Generate JWT
Pass JWT to Live Chat
Validate user
Retrieve user details
In this method, since the JWT token is already signed by Sprinklr, we can choose to omit the chat user signature.
Prerequisites
Before implementing Custom Authentication:
Define the reference token(s) that your application will use to identify a customer.
Provide a user info endpoint (API) that Sprinklr can use to retrieve customer information using these tokens.
Allow the API to accept requests from Sprinklr's servers (whitelist the IPs).
Create the parsed API extension in the environment.
Contact Sprinklr Support for backend config update to the Live Chat application.
Once configured, the client-side integration is expected to pass tokens with hash and hashCreationTime (optional for web) within the customUser object. These tokens serve as the input parameters for the configured API.
When contacting Sprinklr Support, provide:
Partner Name
Partner ID
Environment
Live Chat Application ID
Name of parsed API created in Step 4
Configure the customUser Object
Once Custom Authentication is configured, pass the required reference tokens and authentication hash through the customUser object when initializing Live Chat.
For example:
window.sprChatSettings = window.sprChatSettings || {};window.sprChatSettings = {"appId": "<your-app-id>","customUser": {"tokenA": "xxx","tokenB": "xxx","hash": "xxx"}};
The properties are:
Property | Description |
tokenA, tokenB | Reference token(s) used by your organisation to identify the customer. The number and format of tokens depend on your user identification API. |
hash | Chat user signature |
hashCreationTime | Optional timestamp used when time-based hash expiry is enabled. |
Note: A few possibilities for what the reference token could represent:
User Identifier: A unique identifier for the user.
Access Token: A bearer token that can be used to authenticate and authorize API requests.
JWT (JSON Web Token): A token containing claims that can be decoded to extract a unique user identifier or other relevant attributes.
Optional: Configure Time-Based Hash Expiry
By default, the chat user signature is static and does not expire. You can optionally enable time-based hash expiry by providing hashCreationTime when generating the hash. hashCreationTime represents the timestamp at which the hash was generated.
For example:
window.sprChatSettings = window.sprChatSettings || {};window.sprChatSettings = {"appId": "<your-app-id>","customUser": {"tokenA": "xxx","tokenB": "xxx","hashCreationTime": "<timestamp>","hash": "xxx"}};
When time-based expiry is enabled, the default validity window is ±1 minute around the hash creation time. Contact Sprinklr Support if your implementation requires a different validity window.
How to Generate the Chat User Signature
The chat user signature (hash) is a generated HMAC or Hash-based Message Authentication Code. For HMAC, Sprinklr uses the sha256 hash function. You need to generate HMAC for the following "string" of tokens. Tokens are concatenated to form a string, separated by underscores, as shown below.
Without hash creation time:
tokenA_tokenB With hash creation time:
hashCreationTime_tokenA_tokenB
Important: Always generate the authentication hash on your server so that the secret key used to generate the hash is not exposed in client-side code.
Handle Authenticated and Guest Users
Authenticated Users
For authenticated users, pass the customUser object when initializing Live Chat. If the website is loaded with a user who is already signed in, pass the customUser object again during page load.
Guest users
If the customUser object is not passed or an empty customUser object is passed, Live Chat discards the previously authenticated user's details and associated token and creates a new anonymous user session.
<script>window.sprChatSettings = window.sprChatSettings || {};window.sprChatSettings = {"appId": "app_600000609","customUser": { }</script><script>// live chat embed code</script>
Log Out an Authenticated User
When the user logs out of the host application, initialize Live Chat without the authenticated user's customUser details. This clears the previously authenticated user's information and associated token and allows Live Chat to create an anonymous user session.
Note: Do not continue passing the previous user's authentication details after logout. The customUser object should be provided again when an authenticated user subsequently loads the application.
window.sprChatSettings = window.sprChatSettings || {};window.sprChatSettings = {"appId": "<your-app-id>","customUser": {}};
Security Recommendations
When implementing Custom Authentication:
Generate authentication hashes on your backend rather than in client-side code.
Do not expose the secret used to generate an HMAC signature in browser code.
Pass reference identifiers instead of personally identifiable user information when using the Reference Token authentication method.
Configure the user-details API to accept requests from Sprinklr servers as required by the integration.
Troubleshooting
If Custom Authentication does not work as expected, verify:
The correct Live Chat application ID is being used.
The required customUser properties are being passed.
The signed hash is generated using the expected token order.
If time-based expiry is enabled, hashCreationTime is being included in the hash input.
For JWT authentication, the API credentials and generated JWT are valid.
The configured user-details API is accessible to Sprinklr.
For configuration changes related to the external user-details API or the hash validity window, contact Sprinklr Support.
Sprinklr JWT Token
Prerequisites for Setting Up API to Generate JWT
Register a new Service Email and get a user provisioned on Sprinklr. Example: integration.user@companyname.com. This must be Service Email as it is not tied to a specific employee and the integration is dependent on the user being functional.
Generate API key. In the Sprinklr platform: Navigate to All Settings > Developer Tools > Create New App. Then Manage API Key and create new credentials. Enable client credentials toggle. For detailed instructions, see Developer Tools in Sprinklr.
Generate authorization token using this method: Client Credentials Grant Type.
Step 1: Generate a JWT
API Description
This API call will help you generate a JWT Token using the unique user identifier.
API Endpoint
POST https://api2.sprinklr.com/{env}/api/v2/live-chat/generate-chat-userhash/{appId} Headers
Key | Value | Description |
Content-Type | application/json | Indicates the media type of the request body. |
Authorization | Bearer {access token} | Credential used to authenticate the caller with the server. See the Authorize Section of the Developer Portal to generate this token. |
Key | {API key} | Authenticates the calling application with the server. See the Getting Started guide to generate this key. |
Request Parameters
Parameter | Sub-Parameter | Required? | Description | Type |
customUser | — | Required | Object containing the uniqueID details. | Object |
| uniqueID | Required | Unique identifier for the user. | String |
generateJwtToken | — | Required | Flag indicating whether to generate a JWT token or a hash. | Boolean |
authTokenExpiryInMinutes | — | Required | Expiry time of the JWT token, in minutes. | Integer / Long |
Sample Request
curl -X POST \'https://api2.sprinklr.com/{env}/api/v2/live-chat/generate-chat-userhash/{appId}' \-H 'Authorization: {Enter your Access Token}' \-H 'Key: {Enter your API KEY}' \-H 'Content-Type: application/json' \-d '{"generateJwtToken": "true","authTokenExpiryInMinutes": 300,"customUser": {"uniqueID": "{sampleUniqueID}"}}'
Sample Response
{"data": "<JWT token string>","errors": []}
Note: JWT is passed to Sprinklr. Sprinklr will decode and verify the signature on the JWT - which is a requirement for validation and subsequent 200 (success) on the appHandshake.
Step 2: Pass the JWT to Live Chat
Once the JWT token is generated, pass it through the customUser object when initializing Live Chat. Live Chat will validate the token before continuing the custom user authentication flow.
For example:
window.sprChatSettings = window.sprChatSettings || {};window.sprChatSettings = {"appId": "<your-app-id>","customUser": {"jwt": "xxx"}};
Error Scenarios – appHandshake Call
Error Code | Description |
400 | Invalid input request parameters. |
401 | Returned when any of the following occur: the JWT token is altered or invalid; the Client Channel API returns a status other than 200 OK; the chat application is missing, deactivated, not from a valid origin site, or the request is not from an authorized IP address. |
How Verification Works
When the Sprinklr Live Chat receives the JWT, it:
decodes the header and payload,
verifies the signature using the configured public key,
checks the token claims, such as:
whether exp (expiry time) is still valid,
whether the appId matches the expected application,
whether the partnerId and clientId are recognized, and
any additional policy checks configured for the integration.
If any of these checks fail, the token is rejected.
Validation Rules
Check | Description |
Signature | The token is signed by Sprinklr Live Chat; the signature is verified on every request to detect tampering. |
Claim integrity | Claim values such as appId, partnerId, and clientId are validated against the registered application. |
Expiry | The exp claim is checked against the current time; expired tokens are rejected. |
After Successful Validation
The unique identifier (uniqueID) is extracted from the token's claims. This uniqueID is used to fetch customer details via the customUserKey.uniqueID reference.
Step 3: Retrieve customer data
Once the user is validated in Step 2, Sprinklr initiates a call to the client's API. The purpose of this call is to fetch additional user details and populate them into the profile object, making that information available to agents during the live chat conversation.