POST
Issue SDK Token

Overview

Issue a short-lived SDK token for an external user. Use this token in your frontend with the Vocantly SDK or WebSocket connection. Your backend calls this endpoint; the frontend never sees App ID, public key, or secret key—only the token.
Authenticate with either JWT or API key:
  • JWT: Authorization: Bearer <access_token> (dashboard user).
  • API key: X-Api-Key (pk_…) + X-Api-Secret (sk_…). Use only on your backend; never expose the secret to the frontend.

Path Parameters

string
required
App ID (UUID). Find it in the dashboard Overview, URL, or create-app success modal.

Request Headers

Request Body

string
required
Your app’s user ID (e.g. customer, doctor, patient). Must match participants in the conversation when using external or support type.
string
Display name (optional)
string
Email (optional)
string
Avatar URL (optional)

Example Request

With API key (server-to-server)

With JWT

Response

boolean
Request success status
string
SDK JWT token (e.g. 24h). Use in frontend with SDK or WebSocket.
number
Token expiry in seconds (e.g. 86400 = 24h).
string
Same as external_user_id.

Success (201)

Using the Token

Backend: Call this endpoint (JWT or API key), then return data.token to your frontend. Frontend: Use only the token—never keys.

Error Responses

401 Unauthorized

Invalid JWT or API credentials.

403 Forbidden

App disabled or tenant suspended; or app ID in path does not match API key app.

404 Not Found

App not found.

Security

App ID, public key, and secret key are for backend only. Never expose them to the frontend. The frontend receives only the token from your backend.

Next Steps

WebSocket Auth

WebSocket authentication

SDK Auth

SDK authentication

Create Conversation

Create conversations (including external)