TRaX Edge: live inputs, playback ids, signing keys, webhooks, usage
TRaX Edge is the media CDN without a studio. You create a live input, point
an encoder at it over SRT or RTMP(S), and deliver it to viewers through one or
more playback ids. There is no program, no canvas and no destination list:
what goes in comes out. Everything lives on the same /v1 host, with the same
API keys, error envelope and pagination as the rest of the API, and it is
billed by the viewer-hour from the ledgers GET /v1/usage reads.
A key for Edge needs Edge scopes. None of them is in the default key scopes, so mint a key and tick what the integration needs:
| Scope | What it lets a key do |
|---|---|
live_inputs:read |
List live inputs and read their status. Never a stream key. |
live_inputs:write |
Create, rename, disable and delete live inputs. Includes read. |
live_inputs:ingest |
Fetch and rotate a live input's publish URLs and stream key. A live credential; not included in any other scope. |
playback:write / playback:read |
Create, list and delete playback ids. The same scope that publishes a studio source: it is the same power. |
signing_keys:write |
Create, list, rotate and delete the keys that sign viewer tokens. |
webhooks:write / webhooks:read |
Register, update, test and delete webhook endpoints. |
usage:read |
Read metered usage. |
The common dashboard key holds live_inputs:read and usage:read and can
never see a stream key.
Endpoints
| Method | Path | Scope | What it does |
|---|---|---|---|
| POST | /v1/live-inputs |
live_inputs:write |
Create a live input. The response is its record, not a credential. |
| GET | /v1/live-inputs |
live_inputs:read |
List your live inputs (paged). |
| GET | /v1/live-inputs/{liveInputId} |
live_inputs:read |
Read one, including its live/idle/disabled status. |
| PATCH | /v1/live-inputs/{liveInputId} |
live_inputs:write |
Rename, replace metadata, set the bitrate cap, or disabled: true/false. |
| DELETE | /v1/live-inputs/{liveInputId} |
live_inputs:write |
Delete it and every playback id on it. |
| POST | /v1/live-inputs/{liveInputId}/ingest |
live_inputs:ingest |
Get the publish URLs and stream key. Same shape as a studio source's ingest. |
| POST | /v1/live-inputs/{liveInputId}/ingest/rotate |
live_inputs:ingest |
Replace the stream key; kickPublishers: true cuts whoever is on the old one. The response says whether it did (kicked). |
| POST | /v1/live-inputs/{liveInputId}/playback-ids |
playback:write |
Mint a public or signed playback id with its watch URL, embed snippet and token URL. |
| GET | /v1/live-inputs/{liveInputId}/playback-ids |
playback:read |
List the input's playback ids (paged). |
| DELETE | /v1/playback-ids/{playbackId} |
playback:write |
Revoke one playback id; the others keep working. |
| POST | /v1/signing-keys |
signing_keys:write |
Create an ES256 key. The private half is returned once. |
| GET | /v1/signing-keys |
signing_keys:write |
List your keys: ids and public halves only (paged). |
| POST | /v1/signing-keys/{kid}/rotate |
signing_keys:write |
Mint a successor key; the old one stays valid until you delete it. |
| DELETE | /v1/signing-keys/{kid} |
signing_keys:write |
Delete a key. Tokens signed with it stop verifying at once. |
| POST | /v1/webhook-endpoints |
webhooks:write |
Register an HTTPS receiver. The signing secret is returned once. |
| GET | /v1/webhook-endpoints |
webhooks:read |
List your endpoints (paged). |
| GET | /v1/webhook-endpoints/{endpointId} |
webhooks:read |
Read one endpoint. |
| PATCH | /v1/webhook-endpoints/{endpointId} |
webhooks:write |
Change its URL, events or description, or pause it. |
| DELETE | /v1/webhook-endpoints/{endpointId} |
webhooks:write |
Delete it. |
| POST | /v1/webhook-endpoints/{endpointId}/rotate-secret |
webhooks:write |
Replace the signing secret. The new one is returned once. |
| POST | /v1/webhook-endpoints/{endpointId}/test |
webhooks:write |
Deliver a webhook.test event now and report what your endpoint answered. |
| GET | /v1/usage |
usage:read |
Viewer-seconds and live-input-seconds per hour or day, from the ledgers that bill you. |
Request and response shapes are in the API reference (/v1)
under the Edge tag.
Go live in four calls
API=https://api.traxstreaming.live
KEY=sk_live_… # live_inputs:write, live_inputs:ingest, playback:write
# 1. Create the input.
curl -sS -X POST "$API/v1/live-inputs" \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"name":"Main stage","metadata":{"event":"launch-day"}}'
# → { "id": "3f6c…-uuid", "status": "idle", "streamName": "l/9a41…64-hex", … }
# 2. Fetch the publish credential (a POST: the response is a secret).
curl -sS -X POST "$API/v1/live-inputs/$ID/ingest" \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"protocols":["rtmp"]}'
# → { "streamName": "l/9a41…", "ingestUrls": { "rtmp": { "complete": "rtmp://ingest.traxstreaming.live:1935/l/9a41…?user=…&pass=…", "base": "rtmp://ingest.traxstreaming.live:1935/l/9a41…" } },
# "granted": ["rtmp"], "streamKey": "…" }
# 3. Point your encoder at ingestUrls.rtmp.complete (or base + streamKey).
# 4. Mint a playback id and paste the embed.
curl -sS -X POST "$API/v1/live-inputs/$ID/playback-ids" \
-H "Authorization: Bearer $KEY" -H "Idempotency-Key: $(uuidgen)"
# → { "playbackId": "…", "policy": "public", "watchUrl": "…", "embedHtml": "<iframe …>", "player": { "tokenUrl": "…" } }
A live input's id is a UUID. streamName is the media path, l/ and 64 hex
characters; it is not derived from the id and is safe to log. One ingest
hostname serves every region: it resolves to the nearest point of presence.
SRT is srt://ingest.traxstreaming.live:8890?streamid=publish:<streamName>:<streamKey>:<streamKey>,
RTMP is port 1935 and RTMPS port 1936, both with the key in ?user=&pass=.
Dial complete verbatim and keep it, with streamKey, in a secret store. The
ingest routes sit in the credential rate class (a burst of 5, refilling at 5 a
minute), so fetch once and reuse rather than asking on every connect.
On RTMP the stream key travels as ?user=…&pass=…, exactly as complete has
it. Do not move it to ?token= or any other parameter, and do not repeat it
elsewhere in the URL: a publish whose key appears anywhere else in the URL is
refused with key_in_url, because URLs end up in proxy and access logs.
Public and signed playback
A public playback id is published the moment it exists: anyone holding it
can call POST /v1/playback/{playbackId}/token and watch. Mint one per
partner or per embed so you can revoke a leaked link alone.
A signed playback id makes the token endpoint also require a JWT you
signed, so you decide who may watch, per viewer and per session, with no call
to TRaX in the path:
POST /v1/signing-keysonce. Store theprivateKeyfrom that response; TRaX keeps only the public half and cannot show the private one again.- For each viewer, sign an ES256 JWT with header
kid= the key's id and claimssub= the playback id,aud=trax-playback,expat most 24 hours out. - Your player sends it as
{"token": "<jwt>"}in the body of the token request (or?token=, which lands in access logs, so prefer the body).
Without a token the route answers 401 viewer_token_required; with one that
does not verify, 401 viewer_token_invalid. Rotate with
POST /v1/signing-keys/{kid}/rotate, move your signer to the new kid, and
delete the old key once its last token has expired.
The watch page and the embed
watchUrl is a hosted page, https://watch.traxstreaming.live/p/{playbackId}.
It needs no account and no sign-in. It mints a playback token, plays the
stream over WebRTC, and keeps retrying until the input goes live, so you can
hand the link out before the show starts. Video starts muted, because
browsers refuse autoplay with sound; the viewer unmutes with one click and can
go fullscreen from the player controls.
embedHtml is an <iframe> of the same page with ?embed=1, which drops the
page chrome so the player fills the frame. Keep the allow="autoplay; fullscreen" attribute it ships with. Any site may frame it.
For a signed playback id, append the viewer's JWT to either URL as
?token=<jwt>. The page sends it to the token endpoint in the request body.
Without one, the page tells the viewer they need a pass and stops.
To build your own page instead, load the player element and give it the id:
<script type="module" src="https://watch.traxstreaming.live/embed.js"></script>
<trax-player playback-id="…"></trax-player>
For a signed id, set token="<jwt>" on the element, or assign the element's
token property from your script.
The player re-mints a token only when the one it holds is within 20 seconds
of expiresAt, and it backs off between attempts using the token response's
retryPolicy. The token endpoint allows 10 requests a minute per viewer
address, so a player that minted on every retry would be throttled within a
minute. A 404 from the token endpoint means the id is unknown or disabled,
and the player stops instead of retrying.
Disabling versus deleting
PATCH /v1/live-inputs/{liveInputId} with {"disabled": true} takes an input
out of service and keeps it: every playback id stops minting tokens, the
ingest routes (fetch and rotate) and new playback ids answer 409 conflict,
and a connected publisher is cut.
{"disabled": false} brings it back to idle with the same ids and the same
stream key. Delete the inputs you will not bring back.
The bitrate cap
Every live input has a cap on what its publisher may send: maxBitrateKbps,
video plus audio. Leave it out and the input gets the platform default of
8000 kbps. You can set it lower, or higher up to your account tier's ceiling:
8000 kbps for a new account, 10000 kbps once the account is established. A
value above the ceiling is a 400 invalid_request on create and on PATCH.
The edge measures what actually arrives at the PoP, averaged over about 30 seconds, so a keyframe burst does not count against you. The measurement includes the container (MPEG-TS over SRT, RTMP chunk headers), so a publish may run up to 10% over the cap before it counts as over. Then:
- After one minute over the cap, your endpoints get
live_input.bitrate_exceeded, withmaxBitrateKbps,measuredBitrateKbps,overSinceanddisconnectAt, beside the usualliveInputId,status,metadataandsession. - If the publish is still over two minutes later, it is disconnected.
live_input.disconnectedcarriessession.endReason: "bitrate_exceeded". - For one minute after that, a reconnect is refused. Your encoder sees the connection refused; lower its bitrate and connect again.
A publish that drops back under the cap at any point starts over: the next run over it gets its own minute before a warning. The edge never throttles a publish to fit the cap, because a throttled stream reaches viewers broken and nobody is told why.
A recommended encoder profile that stays well inside the default cap:
| Setting | 1080p30 | 1080p60 | 720p30 |
|---|---|---|---|
| Video | H.264 High, 6000 kbps CBR | H.264 High, 7000 kbps CBR | H.264 Main, 3500 kbps CBR |
| Keyframe interval | 2 s | 2 s | 2 s |
| Audio | AAC-LC, 160 kbps, 48 kHz | AAC-LC, 160 kbps, 48 kHz | AAC-LC, 128 kbps, 48 kHz |
Use CBR, or VBR with a maximum no higher than the cap. A VBR encoder with only a target setting can run well above it on fast motion for longer than a minute.
When the account refuses
TRaX Edge has no free tier, and three facts about the account stop NEW work
(creating a live input, creating a playback id, a new publish, a new viewer).
Each has its own error.code, because each has a different fix:
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 402 | card_required |
No payment method is on file for TRaX Edge. | Add one in the dashboard. |
| 402 | spend_cap_reached |
This calendar month's Edge spend reached the account's cap. | Raise the cap, or wait for the next month (UTC). |
| 403 | suspended |
TRaX Edge is suspended on the account. | Settle the unpaid Edge invoice, or contact support. |
Reads keep working in all three. A viewer asking the token route for one of
the account's playback ids gets the plain 404: the owner's billing state is
not shown to the audience. Holding the maximum number of live inputs is
402 input_limit_reached; the per-input playback id, signing key and webhook
endpoint limits are 409 conflict.
If TRaX Edge itself is unreachable the routes answer 503 unavailable with a
Retry-After header; retry after that many seconds.
Rotating a leaked key
POST /v1/live-inputs/{liveInputId}/ingest/rotate replaces the stream key and
returns the new credential. The old key is refused for every new connection
from that moment. A publisher that is already connected is not affected by the
rotation alone, because a publish is authorised once, when it connects; send
{"kickPublishers": true} to cut it.
The response always carries the new credential, and tells you what became of the kick:
kicked |
kickFailure |
Meaning |
|---|---|---|
true |
absent | You asked for a kick and the publisher was cut. |
false |
absent | You did not ask for a kick. |
false |
kick_unavailable |
You asked for a kick and it could not be performed. |
kick_unavailable is still a 200: the key has rotated, the old key is
already invalid for new connections, and streamKey in that response is the
one now in force. Only a publisher that was connected before the rotation is
still on air, until its connection drops; it cannot reconnect with the old key.
There is no kick-only route. To retry the kick, call the same route again with
kickPublishers: true. That rotates the key again, so configure your
encoder from the latest response, and leave a few seconds between attempts:
each one issues a new key. If you send Idempotency-Key, use a fresh one for
the retry; a repeated key returns the first response and kicks nothing.
Every call to this route rotates. After a timeout, do not resend it blindly:
read the current credential with POST …/ingest, or send an Idempotency-Key
with the rotate so that a repeat returns the first response.
Webhooks and usage
Register a receiver with POST /v1/webhook-endpoints and subscribe to the
event types you want (["*"] for every type in the catalog). Every delivery is signed; see
Webhooks for the signature, the retry policy and the
event catalog. POST /v1/webhook-endpoints/{endpointId}/test fires one
webhook.test event through the normal delivery path and waits for what
your endpoint answered, so you can check your signature verification before
anything real happens. If no attempt completes within about 20 seconds the
route answers 503 unavailable; the event stays queued and is still
delivered. A disabled endpoint takes no deliveries, so the test route answers
409 webhook_endpoint_disabled at once; enable the endpoint with
PATCH {"disabled": false} and test again.
GET /v1/usage returns viewerSeconds and liveInputSeconds per hour or
day, optionally split by liveInput and region, over a window of up to 31
days (hourly) or 366 days (daily). It reads the same ledgers that produce
your invoice: 3600 viewer-seconds is one billable viewer-hour. It has its own
rate bucket (a burst of 10, refilling at 1 a second), sized for a dashboard
that refreshes on a timer.