Skip to main content

How to Create Expiring TURN Credentials

Introduction​

In this guide we will learn how you can create TURN Credentials that expire automatically after some time.

Due to the nature of WebRTC, the TURN Credential has to be sent to the client side, and due to this people worry about the TURN Credential getting leaked from the client side.

If someone stole your TURN Credential they cannot do anything other than use up your TURN Server quota.

To prevent this from happening you can create the TURN Server Credentials using the Metered TURN Server API that expire automatically after some time.

Pre-requisite​

Step 1: Obtain your Metered Domain and Secret Key​

To use the REST API you first need to know your Metered Domain, you can get this info from the Metered Dashboard.

Go to Metered Dashboard -> Developers

Metered Secret Key and Domain

Step 2: Call the Create TURN Credential REST API​

You call the Create TURN Credential REST API and pass the expiryInSeconds parameter in the request body.

For e.g if you specify 7200 as the value for expiryInSeconds the credential will expire after 1hour it is created.

Allow up to 2 minutes for a new credential to propagate

See How to Rotate TURN Credentials for a rotation scheme that keeps credential creation off the critical path.

A newly created TURN credential is not usable the moment the API returns. The credential has to propagate across Metered's global TURN network, which can take up to 2 minutes.

If a client tries to allocate a relay with a brand new credential before propagation has finished, the TURN server can reject the authenticated allocation and no relay candidate is gathered, even though the credential itself is valid. Retrying a short while later succeeds.

This is why an expiring credential should be created ahead of the call rather than at call-setup time.

danger

You should never call this API from the front-end.

Important thing to note here is that you should never call this API from the front-end end, you should create an API in your backend that in-turn calls this API to get the expiring credential which you will use in your front-end.

For e.g if you have built a video conferencing app, and you assume that you meeting lasts 4 hours max, you can create an API on your back that your clients could use to fetch the TURN Server credential.

You can set the expiry for the credential to 14400 (4 hours in seconds), a credential will be created that will automatically stop working after 4 hours.

The expiry is a hard cutoff

When expiryInSeconds elapses the credential stops working immediately, including for calls that are still in progress. Set the lifetime comfortably longer than your longest expected call plus the time the credential may sit cached on a device, and rotate credentials on a schedule instead of shortening the lifetime. The rotation guide covers this.

JavaScript Example​

fetch("https://mla2.metered.live/api/v1/turn/credential?secretKey=e7683ba4dfd4aaba39d9c81f02adabcf2ee0e172a0ac193e", {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "expiryInSeconds": 14400,
    "label": "user-1"
  }),
})

Response​

{
  "username": "5e7dbfbe19c6c158515907a6",
  "password": "wQX5Ze0EExayWJk9",
  "expiryInSeconds": 14400,
  "label": "user-1",
  "apiKey": "56c193debb416385ade8d9a77e277ea33c0f"
}

Then you can call the API Get TURN Credential to and pass the apiKey you got in the response to fetch the ICE Servers array

Request to fetch ICE Servers Array​

fetch("https://mla2.metered.live/api/v1/turn/credentials?apiKey=56c193debb416385ade8d9a77e277ea33c0f")
  .then((response) => {
    if (!response.ok) {
      throw new Error("Network response was not ok");
    }
    const iceServers = await response.json();
    peerConfiguration.iceServers = iceServers
  })
  .then((data) => {
    console.log("TURN server credentials received:", data);
  })
  .catch((error) => {
    console.error("Error fetching TURN server credentials:", error);
  });

The response might look like this:

[
  {
    "urls": "turn:standard.relay.metered.ca:80",
    "username": "5e7dbfbe19c6c158515907a6",
    "credential": "wQX5Ze0EExayWJk9"
  },
  {
    "urls": "turn:standard.relay.metered.ca:80?transport=tcp",
    "username": "5e7dbfbe19c6c158515907a6",
    "credential": "wQX5Ze0EExayWJk9"
  },
  {
    "urls": "turn:standard.relay.metered.ca:443",
    "username": "5e7dbfbe19c6c158515907a6",
    "credential": "wQX5Ze0EExayWJk9"
  },
  {
    "urls": "turn:standard.relay.metered.ca:443?transport=tcp",
    "username": "5e7dbfbe19c6c158515907a6",
    "credential": "wQX5Ze0EExayWJk9"
  }
]

Step 3: Done​

That's it! In this guide we have learned how you can create TURN Credentials using Metered TURN Server API to create TURN Server Credentials that expire automatically after some time.