Book a Demo

Chat API identification

Client User Authentication API

Endpoint: Authenticate User

This endpoint validates access/ID tokens issued by a customer's identity provider (IdP) and returns a user info identifier that can be used for starting a chat from a frontend web or mobile client.

Endpoint Details

URL: {IDP_SRV}/api/authenticate/{customerId}
Method: POST
Content-Type: application/json
Authentication: Not required (tokens are validated internally)

COMM_SRV url for OPO https://app-commsrv.puzzel.com
IDP_SRV url for OPO https://app-consumeridp.puzzel.com

COMM_SRV url for UK https://uk-commsrv.puzzel.com
IDP_SRV url for UK https://uk-consumeridp.puzzel.com

Important Token Requirement

You must provide either an accessToken OR an idToken.

Request Structure

Path Parameters

Parameter	Type	Required	Description	Constraints
`customerId`	string	Yes	The unique identifier of the customer/solution	Min length: 1, Max length: 25

Query Parameters

Parameter	Type	Required	Default	Description
`providerId`	integer	No	Auto-detect	The ID of the identity provider to use. If not specified, the system will attempt to detect the first provider from Organisation Settings -> Visitor Idp.

Request Body

The request body must be a JSON object with the following structure:

Option 1 - Using Access Token:

{
  "codeChallenge": "string",
  "accessToken": "string"
}

Option 2 - Using ID Token:

{
  "codeChallenge": "string",
  "idToken": "string"
}

Important: Provide either accessToken OR idToken, not both.

Field	Type	Required	Description
`codeChallenge`	string	Yes	The PKCE code challenge for the authentication flow
`accessToken`	string	One required	The access token issued by the customer's identity provider. Provide either this OR `idToken`, not both
`idToken`	string	One required	The ID token issued by the customer's identity provider. Provide either this OR `accessToken`, not both

Response Structure

Success Response (200 OK)

When authentication is successful, the endpoint returns:

{
  "userInfoId": "string"
}

Field	Type	Description
`userInfoId`	string	A unique identifier for the authenticated user that can be used in subsequent API calls

Usage Examples

Example 1: Authentication with Access Token (Will use the first Provider)

Request:

POST {IDP_SRV}/api/authenticate/customer123 HTTP/1.1
Host: your-idp-host.com
Content-Type: application/json

{
  "codeChallenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Success Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "userInfoId": "usr_2n4fK8pLmNqR5tXy9vB3wE"
}

Example 2: Authentication with ID Token (Specific Provider)

Request:

POST {IDP_SRV}/api/authenticate/customer123?providerId=456 HTTP/1.1
Host: your-idp-host.com
Content-Type: application/json

{
  "codeChallenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
  "idToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Success Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "userInfoId": "usr_2n4fK8pLmNqR5tXy9vB3wE"
}

Implementation Guidelines for Client Applications

1. Prerequisites

Before using this endpoint, ensure you have:

A valid access token OR ID token from your configured identity provider
The correct solution id
Generated a PKCE code challenge
Provider ID if multiple providers are configured (optional)

2. Using the Response to Start a Chat

After successfully authenticating and receiving the userInfoId, you can use it to start a chat conversation:

Next Step - Start Chat Endpoint:

POST {COMM_SRV}/api/conversation/{conversationId}/route/{queueKey}?userInfoId={userInfoId}&codeVerifier={codeVerifier}

3. Using the Response to Update existing Chat

After successfully authenticating and receiving the userInfoId, you can use it to set identity:

Next Step - Set Identity Endpoint:

POST {COMM_SRV}/api/visitor/setIdentity/{conversationId}
{
  "userInfoId": "userInfoId",
  "codeVerifier": "codeVerifier"
}

Back to Top