Skip to main content

TURN Server Quickstart

This guide takes you from a new Metered account to a WebRTC app that relays through Metered's TURN servers. The steps use the new Metered dashboard.

What you need​

  • A Metered account with a TURN plan. You can sign up here. If you don't have a plan yet, opening Credentials asks you to choose one first.
  • A WebRTC app that creates an RTCPeerConnection.

Step 1: Create a credential​

  1. Log in to the Metered Dashboard and open TURN Server & SFU → Credentials.
  2. Click Create Credential. All the options are optional, so you can create it straight away. To learn what Label, Region and Project do, see Creating TURN Credentials.
Allow up to 2 minutes for a new credential to work

A new credential has to propagate across Metered's global TURN network, which can take up to 2 minutes. If a connection fails straight after you create a credential, wait a moment and try again.

Step 2: Add the ICE servers to your app​

Right after you create the credential, the confirmation shows a snippet you can copy. To get it later, click Get credential on the credential's row, then Show ICE Servers Array. Paste it into your app where it creates the peer connection. It looks like this, with your credential's username and password filled in:

var myPeerConnection = new RTCPeerConnection({
  iceServers: [
    {
      urls: "stun:stun.relay.metered.ca:80",
    },
    {
      urls: "turn:global.relay.metered.ca:80",
      username: "<USERNAME>",
      credential: "<CREDENTIAL>",
    },
    {
      urls: "turn:global.relay.metered.ca:80?transport=tcp",
      username: "<USERNAME>",
      credential: "<CREDENTIAL>",
    },
    {
      urls: "turn:global.relay.metered.ca:443",
      username: "<USERNAME>",
      credential: "<CREDENTIAL>",
    },
    {
      urls: "turns:global.relay.metered.ca:443?transport=tcp",
      username: "<USERNAME>",
      credential: "<CREDENTIAL>",
    },
  ],
});

Use the snippet exactly as the dashboard gives it to you: the TURN hostname depends on your plan and region, and keeping every entry (UDP and TCP on port 80, UDP and TLS on port 443) helps clients behind restrictive firewalls connect.

Alternative: fetch the ICE servers at runtime​

Instead of putting the username and password in your code, your front end can fetch the ICE servers with the credential's API key. The key only gives access to this one credential, so it's safe to use in front-end code.

  1. On the credential's row, click Get credential, then Show API Key, and copy the key.
  2. Find your Metered domain (yourappname.metered.live) under Developers.
  3. Call the Get TURN Credential API and pass the result to RTCPeerConnection:
async function createPeerConnection() {
  const response = await fetch(
    "https://yourappname.metered.live/api/v1/turn/credentials?apiKey=<API_KEY>"
  );
  const iceServers = await response.json();
  return new RTCPeerConnection({ iceServers });
}

Don't confuse this key with the Secret key on the Developers page, which covers your whole account and must stay on your server.

Step 3: Test the relay​

Open the TURN Server Testing Tool, add a TURN server with the hostname from your ICE servers (for example global.relay.metered.ca), port 80, and your credential's username and password, then click Launch Server Test. If the TURN server is reported as reachable, your credential works. If it isn't and you've just created the credential, wait a couple of minutes and try again.

Next steps​