Authentication
In the Widget API, visitor identity is verified with a JWT (accessToken).
Summary
| Mechanism | When | How |
|---|---|---|
| JWT Bearer | Message history and sending messages | Header: Authorization: Bearer <accessToken> |
| JWT (socket) | Socket.IO /message | Handshake: auth.token = accessToken |
The accessToken is obtained from the Visitor Registration response.
JWT (accessToken)
The token returned after registration represents the visitor's chat session. In summary, the token payload includes:
| Field | Description |
|---|---|
chatAppId | Chat application ID |
chatUserId | Widget user ID |
name | Display name |
emailAddress | Optional email |
phone | Optional phone |
externalUserId | Optional external user ID |
REST usage
Authorization: Bearer <accessToken>
The following calls require a Bearer JWT:
Socket.IO usage
import { io } from 'socket.io-client';
const socket = io(`${BASE_URL}/message`, {
auth: { token: accessToken },
withCredentials: true,
});
See Realtime messages for details.
Failed authentication
| Situation | Typical result |
|---|---|
| Invalid / missing JWT (REST) | 401 |
| Invalid / missing JWT (socket) | error event, then the connection is closed |