Slyber

HTTP API

Updated:
Author: Erkin Khidirov

To connect client applications (Web, iOS, Android, Desktop) to Slyber Turn Server, you need to pass a list of server URIs along with temporary username/password credentials to the WebRTC RTCPeerConnection. This can be done in two ways: via the built-in HTTP API.

Fetching Credentials via the HTTP API

Request: GET /api/turn-credentials

URL Parameters (Query Parameters):

  • user_id (optional) - string user identifier for analytics and logs (if omitted, anonymous_<nanoseconds> is generated).
  • ttl (optional) - desired token lifetime in seconds (without the X-Turn-Secret header, this value cannot exceed CREDENTIAL_TTL_SEC from the server configuration).

Headers:

  • X-Turn-Secret: <your_secret> or Authorization: Bearer <your_secret> (required when REQUIRE_SECRET=true).
  • Origin: https://your-domain.com (validated when called directly from a browser).

Request Example (curl):

Bash 
curl -s "http://127.0.0.1:8080/api/turn-credentials?user_id=user_42&ttl=3600" \
     -H "X-Turn-Secret: your-super-secret-turn-key-12345"

Response Example (200 OK):

JSON

JSON 
{
  "username": "1761583600:user_42",
  "password": "K8x9pL2mQ4vR7wT1yZ3aB5cD8eF=",
  "ttl": 3600,
  "uris": [
    "stun:203.0.113.1:3478",
    "turn:203.0.113.1:3478?transport=udp",
    "turn:203.0.113.1:3478?transport=tcp",
    "turns:rtc.example.com:5349?transport=tcp"
  ]
}
Note: The turns:... URI is automatically added to the response if TLS is enabled on the server; furthermore, if a certificate file and a custom REALM (other than turn.local) are configured, the domain name from REALM is automatically substituted into the turns: URI.

Browser Connection Example (JavaScript / WebRTC):

JavaScript 
async function createPeerConnection(userId) {
  // 1. Fetch temporary TURN credentials
  const res = await fetch(`https://turn.example.com:8080/api/turn-credentials?user_id=${encodeURIComponent(userId)}`);
  if (!res.ok) throw new Error('Failed to fetch TURN credentials');
  const turnConfig = await res.json();

  // 2. Pass the received URIs, username, and password to RTCPeerConnection
  const pc = new RTCPeerConnection({
    iceServers: [
      {
        urls: turnConfig.uris,
        username: turnConfig.username,
        credential: turnConfig.password
      }
    ]
  });

  return pc;
}
← Previous Security Next → Monitoring