Create TURN Credential for a Project

Use this endpoint to create a new TURN credential (username/password) under a specific project.

You can authenticate by providing either the secretKey (for your entire application) or the projectApiKey (for a specific project).

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/v2/turn/project/:projectId/credential

<appname> - Replace with the name of your app.

:projectId - The unique ID of the project under which the credential is to be created.

---

Request

POST /api/v2/turn/project/:projectId/credential

Path Parameter

Parameter	Description	Data Type
projectId	The unique ID of the project	String

Query Parameters (Authentication)

Parameter	Description	Data Type
secretKey	Your application's secret key, found in Dashboard → Developers → Secret Key. Only one of secretKey or projectApiKey is required.	String
projectApiKey	The API key for the specific project.	String

Note: Only one of secretKey or projectApiKey is required.

Body Parameters

Parameter	Description	Type	Required
expiryInSeconds	Time (in seconds) after which the credential automatically expires. Must be a positive integer. If omitted, the credential does not auto-expire.	Number	No
label	A custom label to associate with the credential. Useful for identifying or filtering credentials later.	String	No

Example Request Body

{
  "expiryInSeconds": 3600,
  "label": "my-labeled-credential"
}

---

Responses

Success Response

A JSON object containing the newly created credential details:

Field	Description	Data Type
username	The TURN username for this credential.	String
password	The TURN password for this credential.	String
expiryInSeconds	Number of seconds after which this credential expires (if provided).	Number
label	Custom label provided for this credential (if provided).	String
apiKey	The API key used when creating this credential.	String

HTTP Status: 200 OK

Example Success Response

{
  "username": "c7e21d0a812c0c3fdb3af925",
  "password": "lrwWgwswMGQDXA1w",
  "expiryInSeconds": 3600,
  "label": "my-labeled-credential",
  "apiKey": "7fd90780bfa95adb5df34015e2810b71c30f"
}

---

Error Responses

HTTP Status	Message	Description
400	Invalid projectId	The projectId is not a valid MongoDB ObjectId.
400	Project not found	No project matching the given credentials (secretKey or projectApiKey) was found.
400	please enter a positive integer value for expiryInSeconds	The expiryInSeconds body parameter is not a valid positive integer.
403	Maximum credential limit reached. Upgrade to paid plan to create more credentials	The number of active credentials for your current plan has exceeded its limit.
400	Invalid request. Not subscribed to any turn server plan	The application is not subscribed to a TURN server plan.

---

Code Examples

cURL

curl -X POST "https://<appname>.metered.live/api/v2/turn/project/63fdb9f998c1abec0bd3e16c/credential?secretKey=<YOUR_SECRET_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "expiryInSeconds": 3600,
    "label": "my-labeled-credential"
  }'

JavaScript (Fetch)

fetch(
  `https://<appname>.metered.live/api/v2/turn/project/63fdb9f998c1abec0bd3e16c/credential?projectApiKey=<PROJECT_API_KEY>`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      expiryInSeconds: 3600,
      label: "my-labeled-credential",
    }),
  }
)
  .then((response) => response.json())
  .then((data) => console.log("New Credential:", data))
  .catch((error) => console.error("Error:", error));