Authentication

How your mobile/web app authenticates users to join voice rooms.

Overview

Your backend uses your secret API key to authenticate end-users and obtain short-lived session tokens. These tokens are then passed to the client app to connect to the WebSocket signaling server.

Recommended: Auto-auth endpoint

POST/api/auth/auto

Creates or finds a user by username under your tenant, then returns a session token. The user doesn't need a password — your API key is the authenticating credential.

Authorization: Bearer vc_your_api_key_here
Content-Type: application/json

{
  "username": "user_alice_123",

  // optional fields:
  "custom_id":   "42",
  "picture_url": "https://example.com/avatar.png",
  "metadata":    { "role": "admin", "level": 5 }
}

// Response 200
{
  "token": "64-char-hex-session-token",
  "refresh_token": "64-char-hex",
  "expires_in": 3600,
  "user": {
    "id": 7,
    "username": "user_alice_123",
    "custom_id": "42",
    "picture_url": "https://example.com/avatar.png",
    "metadata": { "role": "admin", "level": 5 }
  }
}

Optional fields

Field	Type	Notes
`custom_id`	string	Your own user identifier. 1–128 chars. Unique per tenant. Cannot be changed once set.
`picture_url`	string	Avatar URL. Updated on every token generation if provided.
`metadata`	object	Any JSON object. Stored and returned from GET /api/me. Overwritten each time.

App-ID auth (safe for mobile apps)

POST/api/auth/token

Authenticate with the public app_id (safe to embed in mobile apps) plus a username and password. Use this when you want users to have real passwords.

Content-Type: application/json

{
  "app_id": "vc_app_your_app_id",
  "username": "alice",
  "password": "secret"
}

// Response 200 — same shape as /api/auth/auto

Refreshing tokens

Tokens expire after 1 hour. Use the refresh token to get a new pair without re-authenticating:

POST /api/token/refresh
Content-Type: application/json

{ "refresh_token": "your_refresh_token" }

// Response 200
{
  "token": "new_token",
  "refresh_token": "new_refresh_token",
  "expires_in": 3600
}

Using a token

Pass the token either as an Authorization header or a query parameter:

// As Bearer token header
Authorization: Bearer your_session_token

// Or as query parameter (useful for WebSocket)
GET /ws?token=your_session_token&app_id=vc_app_xxx
GET /api/channels?token=your_session_token

Get current user

GET/api/me

Returns the authenticated user's profile including any custom fields set at token generation time.

Authorization: Bearer your_session_token

// Response 200
{
  "id": 7,
  "username": "user_alice_123",
  "tenant_id": "uuid",
  "custom_id": "42",
  "picture_url": "https://example.com/avatar.png",
  "metadata": { "role": "admin", "level": 5 }
}

Next: Rooms & Channels →