Skip to main content

Authentication

Assistance chat uses two kinds of credentials:

  • Your organization token, which identifies your company. Keep it on your servers and never ship it to a browser or mobile app.
  • A traveller token, which identifies one traveller. This is what your client app uses to create issues, chat, and connect to the real-time socket.

Most chat operations are performed as the traveller. An organization token can create and view your organization's issues and read their conversations, but it cannot send messages, open the socket, or cancel an issue on a traveller's behalf.

1. Get A Traveller Token

Create (or look up) the traveller from your server using your organization token. Each of these endpoints returns a user profile that includes an authentication_token:

EndpointUse when
POST /api/v2/org/:company_id/users/anonymousYou don't want to share personal data. Pass only your own external_id. Idempotent: calling it again returns the same traveller. Requires the Whitelabel Travellers package. See Use Privacy By Design.
POST /api/v2/org/:company_id/users/travellersYou register travellers with their details. See Create a Traveller.
curl -X POST https://www.sitata.com/api/v2/org/$COMPANY_ID/users/anonymous \
-H "Authorization: TKN $ORG_TOKEN" \
-H "Content-Type: application/json" \
-d '{"external_id": "customer-8842"}'
{
"id": "6b0c6f8e-2b1f-4a8e-9d55-0d6f1d3c2a10",
"external_id": "customer-8842",
"anonymous": true,
"authentication_token": "3f1c9a52-7c2e-4b7e-a1f0-5d9e8b6c4a21",
...
}

Store the traveller's id and authentication_token with your customer record, and hand the token to your client app once the customer is signed in to your platform.

2. Call The API As The Traveller

Send the traveller token in the Authorization header and your company id in the Organization header on every request:

Authorization: TKN <traveller authentication_token>
Organization: <company_id>

The Organization header matters for chat: it tells Sitata which organization the traveller is acting under, so their issues go to the assistance provider configured for your organization rather than to Sitata's default team.

3. Get A Socket Token

The real-time socket takes its own signed token. Request one as the traveller:

curl -X POST https://www.sitata.com/api/v2/tokens/for_socket \
-H "Authorization: TKN $TRAVELLER_TOKEN" \
-H "Organization: $COMPANY_ID"
{ "token": "SFMyNTY.g2gDbQAAACQ2YjBjNmY4ZS0yYjFm..." }

Socket tokens are valid for 7 days. Request a fresh one whenever you (re)connect rather than storing it. Organization tokens cannot request a socket token.

Which Token Can Call What

ActionEndpointTraveller tokenOrganization token
Create an issue (recommended)POST /issuesโœ…โ€”
Create an issue for a travellerPOST /org/:company_id/issuesโ€”โœ…
List the traveller's issuesGET /issuesโœ…โ€”
List your organization's issuesGET /org/:company_id/issuesโ€”โœ…
View an issueGET /issues/:idโœ…โœ…
Cancel an issuePATCH /issues/:id/cancelโœ…โ€”
Change an issue's status or close itSitata assistance agents onlyโ€”โ€”
Read an issue's conversationGET /issues/:id/conversationโœ…โœ…
Page through a conversation's messagesGET /conversations/:id/messagesโœ…โœ…
Send a message / upload an attachmentPOST /conversations/:id/messagesโœ…โ€”
Get a socket tokenPOST /tokens/for_socketโœ…โ€”

Organization access is limited to issues that belong to your organization, which are the issues you create with the organization endpoint. Issues a traveller creates themselves are visible to that traveller and to Sitata's assistance team.

Changing an issue's status, including closing it, is reserved for Sitata's assistance agents. Travellers can cancel their own issues.