TURN Relay
WebRTC users behind networks that block UDP can fail to reach each other or a media server directly. A TURN relay passes their traffic along so the connection still works. OSC runs one shared TURN server (coturn) at turn.osaas.io that you can use from your own WebRTC applications.
Availability
The TURN relay is available to workspaces on the PROFESSIONAL plan or above. Workspaces on the FREE and PERSONAL plans get HTTP 402 with the message TURN relay requires PROFESSIONAL plan or above. See Pricing for the plans.
How it works
You do not connect to the TURN server with a fixed username and password. Instead your backend asks OSC for short-lived credentials that belong to your workspace, and hands them to the browser. The credentials expire after the ttl in the response, which is 3600 seconds (one hour).
Your personal access token (PAT) is what authorizes the request for credentials. It must stay in your backend. Never put it in browser code.
Get credentials
Create a PAT on the API Access page of the web console. See Finding Your API Token for the full steps.
Then call the credentials route from your backend:
curl -s -X POST https://deploy.svc.prod.osaas.io/myturn/credentials \
-H "x-pat-jwt: Bearer $OSC_ACCESS_TOKEN"
The response looks like this:
{
"username": "<expiry-unix>:<tenantId>",
"credential": "<generated-credential>",
"ttl": 3600,
"urls": [
"turn:turn.osaas.io:3478?transport=udp",
"turn:turn.osaas.io:3478?transport=tcp",
"turns:turn.osaas.io:443?transport=tcp"
]
}
The first URL is TURN over UDP on port 3478 and the second is TURN over TCP on port 3478. The third, turns: on port 443, is TURN over TLS and is meant for networks that block UDP.
The route can answer with these status codes:
| Status | Meaning |
|---|---|
| 200 | Credentials returned |
| 400 | The PAT is missing, or the x-pat-jwt header is not in the form Bearer <PAT> |
| 402 | The workspace plan is below PROFESSIONAL |
| 403 | The token is not allowed to use this route, for example a scoped token without permission for it |
| 500 | Unexpected error while creating the credentials |
| 503 | The TURN service is unavailable |
Call the route from your backend and keep the result until shortly before it expires, instead of requesting new credentials for every user. A session that lasts longer than the ttl needs fresh credentials from your backend before it expires.
Use it in a browser
Add an endpoint to your own backend that calls the route above and returns the response to your web page. The browser then passes the credentials to the WebRTC connection:
// Ask your own backend for credentials. The PAT stays on the server.
const res = await fetch('/api/turn-credentials');
const { urls, username, credential } = await res.json();
const pc = new RTCPeerConnection({
iceServers: [{ urls, username, credential }]
});
Check it without writing code
You can confirm that your credentials work with the trickle ICE sample.
- Request credentials as shown above.
- Add each URL from the response to the server list on the sample page, with the
usernameandcredentialfrom the same response. - Start candidate gathering on the page.
A candidate of type relay means the server accepted the credentials and allocated a relay.
Limits
- There is one TURN server for now.
- Relayed traffic is not metered or billed yet. Pricing will be published at least 7 days before billing starts.
- The server refuses to relay to peers in private address ranges and to its own address. A relayed client talking to a peer that has its own public IP address, such as a media server like
eyevinn-docker-wrtc-sfu, is the intended path. Two relayed clients that both go through this server may not be able to reach each other. - There is no MCP tool or web console panel for the TURN relay yet. Both are planned.