Issue SDK Token
curl --request POST \
--url https://api.example.com/api/v1/apps/:appId/tokens \
--header 'Content-Type: application/json' \
--data '
{
"external_user_id": "<string>",
"name": "<string>",
"email": "<string>",
"avatar_url": "<string>"
}
'import requests
url = "https://api.example.com/api/v1/apps/:appId/tokens"
payload = {
"external_user_id": "<string>",
"name": "<string>",
"email": "<string>",
"avatar_url": "<string>"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
external_user_id: '<string>',
name: '<string>',
email: '<string>',
avatar_url: '<string>'
})
};
fetch('https://api.example.com/api/v1/apps/:appId/tokens', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/apps/:appId/tokens",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'external_user_id' => '<string>',
'name' => '<string>',
'email' => '<string>',
'avatar_url' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/apps/:appId/tokens"
payload := strings.NewReader("{\n \"external_user_id\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"<string>\",\n \"avatar_url\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/apps/:appId/tokens")
.header("Content-Type", "application/json")
.body("{\n \"external_user_id\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"<string>\",\n \"avatar_url\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/apps/:appId/tokens")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"external_user_id\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"<string>\",\n \"avatar_url\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data.token": "<string>",
"data.expires_in": 123,
"data.user_id": "<string>"
}Provisioning
Issue SDK Token
POST
/
api
/
v1
/
apps
/
:appId
/
tokens
Issue SDK Token
curl --request POST \
--url https://api.example.com/api/v1/apps/:appId/tokens \
--header 'Content-Type: application/json' \
--data '
{
"external_user_id": "<string>",
"name": "<string>",
"email": "<string>",
"avatar_url": "<string>"
}
'import requests
url = "https://api.example.com/api/v1/apps/:appId/tokens"
payload = {
"external_user_id": "<string>",
"name": "<string>",
"email": "<string>",
"avatar_url": "<string>"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
external_user_id: '<string>',
name: '<string>',
email: '<string>',
avatar_url: '<string>'
})
};
fetch('https://api.example.com/api/v1/apps/:appId/tokens', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/apps/:appId/tokens",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'external_user_id' => '<string>',
'name' => '<string>',
'email' => '<string>',
'avatar_url' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/apps/:appId/tokens"
payload := strings.NewReader("{\n \"external_user_id\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"<string>\",\n \"avatar_url\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/apps/:appId/tokens")
.header("Content-Type", "application/json")
.body("{\n \"external_user_id\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"<string>\",\n \"avatar_url\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/apps/:appId/tokens")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"external_user_id\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"<string>\",\n \"avatar_url\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data.token": "<string>",
"data.expires_in": 123,
"data.user_id": "<string>"
}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
| Header | Required | Description |
|---|---|---|
Authorization: Bearer <token> | If using JWT | Dashboard access token |
X-Api-Key | If using API key | App public key (pk_…) |
X-Api-Secret | If using API key | App secret key (sk_…) |
Content-Type | Yes | application/json |
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)
curl -X POST https://dev.vocantly.com/api/v1/apps/YOUR_APP_ID/tokens \
-H "Content-Type: application/json" \
-H "X-Api-Key: pk_xxxxx" \
-H "X-Api-Secret: sk_xxxxx" \
-d '{
"external_user_id": "user_123",
"name": "Jane Doe",
"email": "jane@example.com"
}'
With JWT
curl -X POST https://dev.vocantly.com/api/v1/apps/YOUR_APP_ID/tokens \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d '{
"external_user_id": "user_123",
"name": "Jane Doe"
}'
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)
{
"success": true,
"message": "Token issued successfully",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_in": 86400,
"user_id": "user_123"
}
}
Using the Token
Backend: Call this endpoint (JWT or API key), then returndata.token to your frontend.
Frontend: Use only the token—never keys.
import { Vocantly } from '@vocantly/sdk';
// token from your backend
const client = new Vocantly({
wsUrl: 'wss://ws.dev.vocantly.com/ws',
token,
});
await client.connect();
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)