Usage Concepts

REST-First Design

Turnix exposes a resource-oriented REST API. Requests use predictable URLs, standard HTTP verbs (GET, POST, DELETE, PATCH), status codes, and JSON-encoded responses. Whenever possible, we follow conventional semantics so your existing tooling (cURL, Postman, fetch, etc.) works out of the box.

Authentication with Bearer Tokens

All endpoints require an API Token sent in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Your token implicitly identifies both your Organization and the active Project, so no extra project identifiers are needed. Tokens are scoped and can be rotated without downtime.

Project-scoped tokens – grant access to resources within a single project.
Organization-wide tokens – grant access across every project in the organization.

🔐 Best practice — Keep tokens secret and use them only from trusted server-side code. Never expose them in client-side apps or public repositories.

Geo-Distributed TURN Infrastructure

The Turnix TURN fleet spans multiple regions worldwide. When you request ICE credentials, the platform automatically selects the nearest operational TURN server based on:

GeoIP of the caller.
Explicit fixed_region or preferred_region hints.

You can query /regions to list all currently available regions as shown in the SDK examples.

Clients & Rooms

Many applications benefit from tracking who started a call, who received it, and which logical room the participants belong to. Turnix lets you attach three optional fields when requesting credentials:

Field	Purpose
`initiator_client`	Identifier for the endpoint that starts a call
`receiver_client`	Identifier for the endpoint that receives a call
`room`	Logical grouping for multi-party sessions

These attributes are surfaced in the Turnix Console, allowing you to drill down by client or room, correlate sessions with your own IDs, and generate direct links back to your system.

👉 See Clients and Rooms for detailed guidelines, limitations, and code samples.

Time-to-Live (TTL) & Renewal

ICE credentials expire automatically. Specify a ttl (seconds) to fit your session length and refresh before expiry using the same SDK call. Shorter TTLs reduce the blast radius of leaked credentials.

Next Steps

Explore the Tutorials section for hands-on guides.
Integrate one of the Turnix SDKs (Dart, JS, Go) to shorten boilerplate.
Head to the API Reference for detailed endpoint schemas.

REST-First Design​

Authentication with Bearer Tokens​

Geo-Distributed TURN Infrastructure​

Clients & Rooms​

Time-to-Live (TTL) & Renewal​