Skip to navigation
API OverviewBrowser calling

Create a client token

View as Markdown

Create a token that lets one browser or SIP-over-WebSocket client connect to the platform as an identity. Use any SIP-over-WebSocket client that supports WebRTC, such as JsSIP or SIP.js: connect to ws_url, authenticate with username and password, and use sip_uri as the client’s own address.

An identity can hold at most 2 live tokens, so a client can rotate a token before the old one expires. A third request returns 409. Only one token per identity can be connected at a time, and an identity has at most one Session at a time.

Browser connections are accepted only from the network addresses configured for the application. If none are configured, this operation returns 403.

The password is returned only by this response; keep it out of logs. Retrying with the same Idempotency-Key within 60 seconds replays the original response; the replay never outlives expires_at.

A token only gates new connections. A call already in progress on a token that was revoked, replaced, or has expired continues until it hangs up; end it with DELETE /v1/sessions/{uuid}.

Authentication

AuthorizationBearer

Send Authorization: Bearer <app_uuid>:<api_key> using an active API key. See Authentication for details.

Headers

Idempotency-KeystringOptionalformat: "^[a-zA-Z0-9._-]*$"<=128 characters

Optional key for safely retrying mutating requests. An explicitly empty header is treated like omission and does not enable replay protection. See Idempotency for details.

Request

This endpoint expects an object.
identitystringRequiredformat: "^[a-z0-9._-]{1,64}$"

Identity the token authenticates: 1 to 64 lowercase letters, digits, dots, underscores, or hyphens. It is not normalized; any other value returns 400.

ttl_secondsintegerOptional60-31536000

Token lifetime in seconds. Defaults to 3600; range 60 to 31536000.

Response headers

traceparentstringOptionalformat: "^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$"=55 characters

Server-owned W3C Trace Context for correlating this response with support and observability data. It is present on successful and error responses. When a request has a valid traceparent, the server links the incoming context to its own trace and returns that trace identifier.

Response

Token created.
client_token_idstring
Token identifier. Use it to read or revoke the token.
created_atdatetime
When the token was created.
expires_atdatetime
When the token stops authenticating new connections.
ice_serverslist of objects

ICE servers for the browser’s RTCPeerConnection, in RTCIceServer format. Currently always empty.

identitystring
Identity the token authenticates.
passwordstring
SIP digest authentication password. It is shown only once.
protocolenum

Signaling protocol: SIP over secure WebSocket (RFC 7118).

Allowed values:
sip_uristring

The client’s own SIP address, sip:<identity>@<domain>.

usernamestring

SIP digest authentication username. It equals client_token_id.

ws_urlstringformat: "uri"
Secure WebSocket URL to connect to.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
406
Not Acceptable Error
409
Conflict Error
413
Content Too Large Error
415
Unsupported Media Type Error
422
Unprocessable Entity Error
500
Internal Server Error
503
Service Unavailable Error