Create TURN Credential

This endpoint is used to create a TURN Server Credential.

Allow up to 2 minutes for a new credential to propagate

See How to Rotate TURN Credentials for the recommended implementation.

A newly created TURN credential is not usable the moment this endpoint 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.

Create credentials ahead of time from your back-end instead of at call-setup time, and reuse them across calls.

POST

    https://<appname>.metered.live/api/v1/turn/credential

<appname> - replace it the name of your app.

Request

POST /api/v1/turn/credential

Query Parameters

Parameter	Description	Data Type
secretKey	The secret key for app identification	String

Request Body

The request body should be a JSON object with the following fields:

Field	Description	Data Type
expiryInSeconds	(optional) The time in seconds for the credential to expire	Integer
label	(optional) An label for the credential	String

Responses

Success Response

A JSON object containing the created TURN credential information:

Field	Description	Data Type
username	The username of the credential	String
password	The password of the credential	String
expiryInSeconds	The time in seconds for the credential to expire	Integer
label	The label for the credential	String
apiKey	The apiKey of the credential	String

HTTP Status: 200 OK

Body:

{
  "username": "<username>",
  "password": "<password>",
  "expiryInSeconds": 3600,
  "label": "<label>",
  "apiKey": "<apiKey>"
}

Error Responses

• Invalid Expiry Time:

  HTTP Status: 400 Bad Request

  Body:

  {
    "message": "please enter a positive integer value for expiryInSeconds"
  }

Code Examples

JavaScript (Fetch API)

fetch("https://<appname>.metered.live/api/v1/turn/credential?secretKey=<YOUR_SECRET_KEY>", {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "expiryInSeconds": 3600,
    "label": "exampleLabel"
  }),
})