API Introduction
Updated
The Xirsys API provides TURN credentials, WebSocket signaling access, channel management, and TURN/STUN usage statistics. Make authenticated API requests from a trusted backend so your Xirsys secret is never exposed to browsers or distributed client applications.
Default API gateway: use https://global.xirsys.net unless Xirsys Support has instructed you to pin a regional gateway.
Gateways and Region Selection
global.xirsys.net routes the API request to a nearby, healthy Xirsys API region. "Nearby" refers to the system making the API request, normally your backend, not automatically to the browser or device that will use the returned credentials.
For a normal TURN request, the selected TURN region reflects the API request and the regions enabled for your account. If your backend is far from the end user, use end-user geo routing so Xirsys can select TURN for the user's location. New Free accounts can use all available regions during their first 30 days; after the trial they use their assigned home TURN region. Paid accounts retain geo routing.
Regional API gateways remain available for integrations that intentionally pin API traffic. The region access shown in the Xirsys dashboard is authoritative for your account. Production plans include the production-region coverage advertised for that plan; developer or legacy accounts may be region-limited.
| Gateway | Location |
|---|---|
global.xirsys.net | Globally routed API entry point (recommended) |
ws.xirsys.com | US West |
us.xirsys.com | US East |
es.xirsys.com | Europe |
fr.xirsys.com | Frankfurt |
bs.xirsys.com | Bangalore |
tk.xirsys.com | Tokyo |
hk.xirsys.com | Hong Kong |
ss.xirsys.com | Singapore |
ms.xirsys.com | Sydney |
sp.xirsys.com | São Paulo |
to.xirsys.com | Toronto |
jb.xirsys.com | Johannesburg |
Do not change an existing pinned gateway solely from this table. Confirm account access and any migration plan with Xirsys Support first.
Service Overview
| Service | Prefix | Purpose |
|---|---|---|
| TURN (ICE) | _turn |
Issue short-lived STUN/TURN credentials for WebRTC. |
| Signaling host | _host |
Select a healthy WebSocket signaling host. |
| Signaling token | _token |
Authorize one peer on a signaling channel. |
| Channels | _ns |
Create, list, and delete channels. |
| Statistics | _stats |
Read hourly TURN/STUN usage rollups. |
Authentication
Authenticate REST requests with HTTP Basic authentication using your Xirsys account identifier and secret. Send the resulting Authorization header only over HTTPS.
Authorization: Basic base64(IDENT:SECRET)A normal success response has "s": "ok" and places the result in v. Always check the HTTP status and the response envelope. Redact authorization headers, signaling tokens, and TURN credentials from application logs.
Use the Xirsys API Tester for an interactive request check, or open the API quick reference (Markdown) for a compact implementation guide that also works well as context for AI coding assistants.