SendexaDocs
Dash
In-App Chat SDK
Beta
REST

Users & Auth

Identify end users with your own userId, mint short-lived chat session tokens from your backend, and keep dashboard credentials off every client device.

Server-only mint

Tokens are issued only with your dashboard Basic Auth. Clients never hold the master key.

Configurable TTL

300–86400 seconds per token. Short sessions for web; longer for trusted mobile apps.

Your user ids

Bring your own userId — no separate Sendexa login for end users.

Scoped claims

Tokens encode business + user identity and cannot create channels without membership.

Default TTL

3600s

1 hour

Min / Max TTL

5m–24h

300–86400 seconds

userId max

128

characters

Mint rate

60/min

per API key (soft)

POST
/v1/chat-sdk/users/token
Beta

Request Body

application/json
JSON
{
  "userId": "user_01HZX9K2M",
  "displayName": "Ama Mensah",
  "ttl": 3600
}
FieldTypeRequiredDescription
userIdstring
required
Your application's unique user id. Immutable for a real person. Used in membership and message.userId.
displayNamestringoptionalShown in channel UIs and presence. Updated when you mint a new token with a new value.
ttlnumberoptionalSeconds until expiry. Default 3600. Range 300–86400.

Response

JSON
{
  "success": true,
  "code": "CHAT_USER_TOKEN_ISSUED",
  "message": "User chat token minted.",
  "requestId": "REQ-1782001100001",
  "timestamp": "2026-07-12T10:00:00.000Z",
  "data": {
    "userId": "user_01HZX9K2M",
    "displayName": "Ama Mensah",
    "token": "chat_usr_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJ1c2VyXzAxSFpYOUsyTSIsImV4cCI6MTc4Mzg1NDgwMH0.signature",
    "expiresAt": "2026-07-12T11:00:00.000Z",
    "ttl": 3600
  }
}

Code Examples

Bash
curl -X POST 'https://api.sendexa.co/v1/chat-sdk/users/token' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic YOUR_DASHBOARD_BASE64_TOKEN' \
  -d '{
    "userId": "user_01HZX9K2M",
    "displayName": "Ama Mensah",
    "ttl": 3600
  }'

Token Lifecycle

Mint
After your login succeeds, call POST /v1/chat-sdk/users/token and hand data.token to the client once.
Refresh

Re-mint with the same userId before expiresAt. On the client, apply the new token without dropping the session:

JavaScript
await chat.updateToken(newToken);
End session

On logout, disconnect the client. Tokens expire automatically at expiresAt; keep TTL short so stolen tokens die quickly.

JavaScript
await chat.disconnect();

Using the Token in the Client

JavaScript
import { SendexaChat } from '@sendexa/chat-sdk';


// token from YOUR backend only
const chat = SendexaChat.init({ token: userChatToken });


chat.on('error', (err) => {
  if (err.code === 'TOKEN_EXPIRED' || err.code === 'UNAUTHORIZED') {
    // Fetch a fresh token from your API, then:
    // await chat.updateToken(freshToken);
  }
});


await chat.connect();
// The WebSocket and REST history calls use the user token automatically.
Identity Rules
RuleGuidance
Stable userIdNever recycle a userId for a different person; membership and history are keyed by it.
One person, one idMap all devices for the same login to the same userId so presence and read state merge correctly.
Agents & botsGive support agents and bots their own userIds (e.g. agent_*, bot_*). Mint tokens for them the same way.
displayNameOptional cosmetic field; do not use it for authorization decisions.
PIIPrefer opaque ids. If you must use phone/email-derived keys, hash them first.

HTTP Status Codes

CodeStatusDescription
200OKToken minted successfully
400Bad RequestMissing userId, invalid ttl, or validation failure
401UnauthorizedInvalid or missing Basic Auth credentials
403ForbiddenChat SDK not enabled for this business
429Too Many RequestsToken mint rate limit exceeded
Error codeCause
INVALID_USER_IDuserId missing, empty, or exceeds 128 characters
INVALID_TTLttl outside 300–86400 or not an integer
UNAUTHORIZEDMissing/invalid Authorization: Basic header
CHAT_SDK_DISABLEDProduct not enabled for the business
RATE_LIMIT_EXCEEDEDToo many mint requests — back off and retry