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 minutes (default 10). 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

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 addresses in the namespace except your own, keyed as peer_0, peer_1, etc. Addresses expire from the namespace after 10 minutes of no activity.

Usage Pattern

Have both clients poll Exchange after getting relay credentials. Each client publishes its address and reads the others. Once both addresses are available, use them to exchange WebRTC offers/answers out-of-band.

Two-Bucket Balance

Your account has two balance pools:

Balance Checks at Credential Time

Before issuing credentials, Tosses estimates whether your balance can cover the session. If the check fails, you get a 402.

The reserve requirement depends on your current active sessions and the requested TTL:

• Base reserve: 0.05 GB per currently active session.
• Long TTL (> 30 min): Additional 5 GB per hour of TTL beyond the default, unless your app has usage history; then it's estimated from your historical average throughput.
• Gateway calls: Reserve is calculated for 1 allocation only, not your total active session count.

These are reserves, not charges. Actual deductions happen based on real egress bytes at session close.

Negative Balance

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