POST /v1/call/session-token

Issues a short-lived session token that a client can use to connect to the WebSocket signaling endpoint.

Description

The application backend calls this endpoint after it has authenticated the user and confirmed that the call is allowed.

Headers

Header	Required	Description
`Content-Type: application/json`	Yes	Request body format.
`X-BCS-Product-Key-ID`	Yes	Product key ID issued by Blendlix.
`X-BCS-Product-Secret`	Yes	Product secret issued by Blendlix.

Request body

Field	Type	Required	Description
`product`	string	Optional when product auth maps the key to one product	Product namespace.
`context_type`	string	Yes	Application-defined context type.
`context_id`	string	Yes	Application-defined context ID.
`user_id`	string	Yes	Participant ID from the application.
`role`	string	Yes	Participant role in the application.
`display_name`	string	Yes	Name shown in call UI.
`device_id`	string	No	Client device ID.
`app_version`	string	No	Client application version.
`allowed_peer_role`	string	Yes	Receiver role this participant may call.

{
  "product": "example_application",
  "context_type": "session",
  "context_id": "SESSION-1001",
  "user_id": "caller-123",
  "role": "caller",
  "display_name": "Caller One",
  "device_id": "web-01",
  "app_version": "1.0.0",
  "allowed_peer_role": "receiver"
}

Success response

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2026-07-04T12:00:00Z",
  "ws_url": "wss://rtc-svc.blendlix.com/v1/ws",
  "ice_servers": [
    {
      "urls": ["stun:turn-rtc-svc.blendlix.com:3478"]
    },
    {
      "urls": ["turn:turn-rtc-svc.blendlix.com:3478?transport=udp"],
      "username": "temporary_or_configured_username",
      "credential": "temporary_or_configured_credential"
    }
  ],
  "user": {
    "user_id": "caller-123",
    "role": "caller",
    "display_name": "Caller One"
  },
  "allowed_actions": [
    "call.invite",
    "call.accept",
    "call.reject",
    "call.cancel",
    "call.end",
    "call.connected",
    "webrtc.offer",
    "webrtc.answer",
    "webrtc.ice_candidate"
  ]
}

Error responses

Status	Code	Meaning
`400`	`INVALID_REQUEST_BODY`	Request body is missing or invalid.
`400`	`PRODUCT_REQUIRED`	Product is required.
`400`	`CONTEXT_TYPE_REQUIRED`	`context_type` is required.
`400`	`CONTEXT_ID_REQUIRED`	`context_id` is required.
`400`	`ROLE_REQUIRED`	`role` is required.
`400`	`USER_ID_REQUIRED`	`user_id` is required.
`400`	`DISPLAY_NAME_REQUIRED`	`display_name` is required.
`400`	`ALLOWED_PEER_ROLE_REQUIRED`	`allowed_peer_role` is required.
`401`	`PRODUCT_AUTH_KEY_ID_REQUIRED`	Product key ID header is missing.
`401`	`PRODUCT_AUTH_SECRET_REQUIRED`	Product secret header is missing.
`401`	`PRODUCT_AUTH_INVALID_KEY`	Product key ID is unknown or disabled.
`401`	`PRODUCT_AUTH_INVALID_SECRET`	Product secret is incorrect.
`403`	`PRODUCT_AUTH_PRODUCT_MISMATCH`	Product in the request does not match the authenticated key.
`429`	`BOOTSTRAP_IP_RATE_LIMITED`	Too many token requests from the same IP.
`429`	`BOOTSTRAP_KEY_RATE_LIMITED`	Too many token requests for the same product key.

Example

curl -X POST https://rtc-svc.blendlix.com/v1/call/session-token \
  -H "Content-Type: application/json" \
  -H "X-BCS-Product-Key-ID: your_key_id" \
  -H "X-BCS-Product-Secret: your_secret" \
  -d '{
    "product": "example_application",
    "context_type": "session",
    "context_id": "SESSION-1001",
    "user_id": "caller-123",
    "role": "caller",
    "display_name": "Caller One",
    "allowed_peer_role": "receiver"
  }'

API Reference Overview GET /v1/calls/history