1. Get an API Key

Sign up at the dashboard. Your first 1 GB is free with no card required. Create an app and copy the API key (it's only shown once).

2. Request Credentials (Server-Side)

3. Build the ICE Server Config

The response is already a valid ICE server object — pass it directly to the client:

Credential Lifetime

Credentials expire after expiry_ttl seconds (default 600). Expiry only prevents new allocations; active relay sessions aren't terminated when credentials expire. For long-lived sessions, refresh credentials before expiry and call pc.setConfiguration + pc.restartIce().

Request Body

Example Request

Response: Regular Credentials

When to Use a Gateway

For multiplayer rooms or any session where multiple users need to share the same relay. Instead of generating one long-lived credential for the room (which expires), you generate a gateway once and hand each user their own short-lived credential from it.

Gateways never expire. Balance is checked each time a credential is issued through them, not upfront for the whole session.

Step 1: Create a Gateway

Response:

Store the gateway ID server-side for the lifetime of your room. It encodes the relay assignment and your app ID.

Step 2: Issue Credentials per User

Each time a user joins, call credentials with the gateway ID. You get back 3-minute credentials routed to the same relay as all other members of that gateway.

Response:

Relay Pinning Logic

When a gateway credential is requested, Tosses looks for any active allocations using that gateway. If found, it routes to that relay regardless of the original relay ID. If not, it picks the best available relay for the host IP, the same way a regular credential does.

This means even if the first user disconnects and a new one joins, as long as any session is active on the gateway's relay, that relay stays pinned.

Request Body

Response

Returns all entries in the namespace keyed as data_0, data_1, etc. Each entry is a separate string added by a different write. The namespace expires 10 minutes after the last write. Rate limited to 8 requests / 10 seconds.

Example: WebRTC signaling

Peer A writes its SDP offer; peer B polls until it appears, then writes its answer to a separate namespace.

Other use cases

Exchange is just a short-lived key-value store, you can use it for anything that needs two parties to hand off a small piece of data without a server in between:

• Passing a relay credential or invite token to a peer joining a room
• Sharing a temporary public key before establishing an encrypted channel
• Coordinating a rendezvous point (IP + port) for a direct UDP connection
• Sending a one-time config blob to a device on first boot

Two-Bucket Balance

Your account has two balance pools:

Balance Checks at Credential Time

Before issuing credentials, Tosses estimates how much data the session is likely to consume and checks that your balance can cover it. If your balance is zero or the estimate exceeds your balance, you get a 402. These are forward-looking reserves, not charges — actual billing is based on real egress bytes reported when sessions close.

Estimates use your app's historical averages: throughput (Mbps), allocation length, and allocations per session. Apps with no history use a conservative 2 Mbps default.

For regular credentials: the estimate accounts for all currently active sessions and allocations alongside the new one, scaled by the requested credential TTL.

For gateway credentials: the estimate projects one new allocation at your app's average throughput and duration, on top of however many allocations are already active on that gateway.

Negative Balance

Credential creation is blocked at zero balance. Your balance can go slightly negative if a session uses more than was estimated; you'll need to top up before issuing new credentials. Low-balance email notifications are configurable per account.