WebSocket Authentication

const ws = new WebSocket('wss://ws.dev.vocantly.com/ws', [token]);

const ws = new WebSocket('wss://ws.dev.vocantly.com/ws', {
  headers: { 'Authorization': `Bearer ${token}` }
});

const ws = new WebSocket(`wss://ws.dev.vocantly.com/ws?token=${token}`);

{
  "sub": "external_user_id",
  "app_id": "app-uuid",
  "type": "sdk_user",
  "exp": 1234567890,
  "iat": 1234567890
}

1. Your backend calls POST /apps/:id/tokens (JWT or X-Api-Key + X-Api-Secret)
2. Your backend returns the token to your frontend (never keys)
3. Frontend connects to WebSocket with the token
4. Server validates token → Connection established
5. Token expires → Reconnect with new token from your backend

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", "email": "jane@example.com"}'

{
  "type": "error",
  "error": "Invalid token"
}

{
  "type": "error",
  "error": "Token expired"
}

class WebSocketManager {
  private ws: WebSocket | null = null;
  private refreshTimer: NodeJS.Timeout | null = null;

  async connect(token: string) {
    this.ws = new WebSocket('wss://ws.dev.vocantly.com/ws', {
      headers: { 'Authorization': `Bearer ${token}` }
    });

    this.ws.onopen = () => {
      // Schedule token refresh 1 minute before expiry
      this.scheduleRefresh(14 * 60 * 1000);
    };

    this.ws.onclose = (event) => {
      if (event.code === 1008) {
        // Token invalid/expired, get new token and reconnect
        this.handleTokenExpired();
      }
    };
  }

  private scheduleRefresh(delay: number) {
    this.refreshTimer = setTimeout(async () => {
      const newToken = await this.fetchNewToken();
      await this.reconnect(newToken);
    }, delay);
  }

  private async handleTokenExpired() {
    const newToken = await this.fetchNewToken();
    await this.connect(newToken);
  }

  private async fetchNewToken(): Promise<string> {
    const response = await fetch('/api/sdk-token', { credentials: 'include' });
    const { token } = await response.json();
    return token;
  }

  private async reconnect(token: string) {
    if (this.ws) {
      this.ws.close();
    }
    await this.connect(token);
  }
}

import { Vocantly } from '@vocantly/sdk';

// token from your backend (POST /apps/:id/tokens)
const client = new Vocantly({
  wsUrl: 'wss://ws.dev.vocantly.com/ws',
  token
});

await client.connect();

client.on('error', async (error) => {
  if (error.message?.includes('Token expired')) {
    const newToken = await fetch('/api/sdk-token', { credentials: 'include' }).then(r => r.json()).then(d => d.token);
    client.updateToken(newToken);
    await client.connect();
  }
});