Authentication
API Key
Format
A Vurbo.ai API Key has the format vas_ followed by a 32-character random string:
vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW
How to Obtain
- Log in to the Vurbo.ai Dashboard:
https://vas-poc.vurbo.ai/dashboard - Go to the "API Keys" page
- Click "Create New Key"
- Copy and securely store the API Key
Note: The API Key is displayed only once, so be sure to save it.
Authentication Methods Overview
The VAS API uses different authentication methods depending on the API type:
| API Type | Authentication Method | Description |
|---|---|---|
| REST API | X-API-Key Header | Use the API Key directly |
| SSE API | X-API-Key Header or ?api_key= Query | Both methods are supported |
| WebSocket | Ticket mechanism | Exchange the API Key for a one-time ticket |
| Viewer API | Token / no authentication | Identified via a share token |
Method 1: X-API-Key Header
Applies to REST API and SSE API.
Place the API Key in the HTTP header:
X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW
REST API Example
curl -X GET "https://vas-poc.vurbo.ai/api/v1/tasks" \
-H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"
SSE API Example
The SSE API supports two authentication methods:
Method A: Header (requires the fetch API; the browser's native EventSource does not support custom headers):
const response = await fetch(
'https://vas-poc.vurbo.ai/api/v1/sse/history/transcribe/{taskId}',
{
headers: { 'X-API-Key': 'vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW' }
}
);
const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
const text = decoder.decode(value);
// Parse SSE events...
}
Method B: Query Parameter (can be used with the browser's native EventSource):
const eventSource = new EventSource(
'https://vas-poc.vurbo.ai/api/v1/sse/history/transcribe/{taskId}?api_key=vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW'
);
eventSource.addEventListener('init_metadata', (e) => {
const data = JSON.parse(e.data);
console.log(data);
});
Note: The query parameter method exposes the API Key in the URL. Use it only in scenarios where headers are not available (such as the browser's native EventSource).
Method 2: Ticket Mechanism (WebSocket Only)
WebSocket connections use a ticket mechanism for authentication, which avoids exposing the API Key in the connection URL.
Flow
1. Exchange for a ticket via REST API → POST /api/v1/auth/ticket (using X-API-Key)
2. Connect using the ticket → WebSocket Sec-WebSocket-Protocol: ticket.{TICKET}
Step 1: Obtain a Ticket
curl -X POST "https://vas-poc.vurbo.ai/api/v1/auth/ticket" \
-H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"
Response:
{
"ticket": "aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
"expires_in": 60
}
| Field | Type | Description |
|---|---|---|
ticket | string | One-time ticket (32 characters) |
expires_in | int | Validity period (seconds) |
Step 2: Connect to the WebSocket Using the Ticket
Place the ticket in Sec-WebSocket-Protocol, in the format ticket.{TICKET_VALUE}:
const ws = new WebSocket('wss://vas-poc.vurbo.ai/ws', [`ticket.${ticket}`]);
ws.onopen = () => {
console.log('Connected! Protocol:', ws.protocol);
};
Node.js Example:
const WebSocket = require('ws');
const ws = new WebSocket('wss://vas-poc.vurbo.ai/ws', [`ticket.${ticket}`]);
Ticket Characteristics
| Characteristic | Description |
|---|---|
| Validity period | 60 seconds |
| Number of uses | Can be used only once (deleted immediately after use) |
| Security | The API Key is not exposed in the WebSocket connection |
Ticket Error Codes
| Error Code | Description |
|---|---|
ticket_invalid | Ticket invalid or expired |
ticket_expired | Ticket expired |
ticket_already_used | Ticket already used |
ticket_validation_failed | Ticket validation failed |
For the full API specification, see Auth Ticket API.
Method 3: Token Authentication (Viewer)
The broadcast viewer API does not require an API Key; viewers are identified via the broadcast share token.
Viewer SSE Connection
// Public broadcast
const eventSource = new EventSource(
'https://vas-poc.vurbo.ai/broadcast/{token}/text'
);
// Password-protected broadcast (you must first obtain a viewer_access_token through password verification)
const eventSource = new EventSource(
'https://vas-poc.vurbo.ai/broadcast/{token}/text?viewer_access_token={token}'
);
For details, see Viewer API and Broadcast Viewer SSE.
Authentication Errors
| Error Code | HTTP | Description | Recommended Action |
|---|---|---|---|
auth_missing_api_key | 401 | API Key is required | Confirm the request includes the X-API-Key header |
auth_invalid_api_key | 401 | Invalid API key | Verify that the API Key is correct |
auth_invalid_key_format | 401 | Invalid API key format | Confirm the format is vas_ followed by a 32-character string |
auth_key_expired | 401 | API key expired | Request a new API Key |
auth_key_disabled | 401 | API key disabled | Contact technical support |
auth_user_disabled | 403 | User disabled | Contact technical support |
auth_budget_exceeded | 402 | Monthly budget exceeded | Wait for the monthly budget to reset or adjust the budget |
Error Response Example
{
"type": "error",
"data": {
"error_code": "auth_invalid_api_key",
"severity": "fatal",
"message": "Invalid API key",
"context": "auth",
"request_id": "req_abc123xyz789",
"timestamp": "2026-01-15T10:30:45.123Z"
}
}
For the full list of error codes, see Error Code Reference.
Budget and Limits
| Item | Description |
|---|---|
| Monthly budget | Set per plan via monthly_budget_usd; returns HTTP 402 when exceeded |
| Concurrent connections | Depends on the plan |
Security Recommendations
- Do not hard-code the API Key in front-end code
- Do not commit the API Key to version control systems
- Store the API Key in environment variables or a secrets management service
- Rotate the API Key regularly
- For WebSocket connections, use the ticket mechanism to avoid exposing the API Key in the URL
Version: V1.5.7 Last Updated: 2026-05-20