Console (allocations and join codes)

The Arena console has two netcode screens that together cover the whole join path: Allocations mints the join codes that peers redeem, and API keys holds the API keys, the allocation API reference, and the signing keys that sign allocation tokens. Both screens read live FirstByte data — an org with no allocations and no keys shows empty states rather than samples. This page explains what the fields on those screens mean. For the Unity transport swap, lanes, and the wire model, see the netcode details and cookbook pages.

What an allocation is

An allocation is a workspace-scoped record that binds one session namespace to one relay endpoint, plus a join code that peers redeem to reach it. The allocations table lists one row per allocation:

Column	Meaning
Join code	The shareable code peers redeem. Copyable from the row.
Namespace	The session namespace the allocation was minted for.
Workspace	The workspace (tenant) the allocation belongs to.
Region	The edge the allocation was pinned to: `auto`, `fra`, or `sg`.
Redeemed	Peers redeemed so far, over the allocation’s max players.
Expires	When the allocation stops being active.
State	Allocation state chip (`active` while redeemable).
Tags	Resource tags, stored against the `netcode_allocation` kind.

Rows are fetched by fleetGames.netcodeAllocations.list({ orgId }). Tags are editable inline and are scoped to the same org.

KPIs on the allocations screen

fleetGames.netcodeAllocations.kpi({ orgId }) feeds the strip above the table:

KPI	Source field	What it counts
Active allocations	`active_allocations`	Minted and not yet expired.
Peers redeemed	`peers_redeemed`	Join codes used.
Token alg	`token_alg`	The algorithm of the org’s active JWKS key. Shown as a warning when the org has no signing key.
Default TTL	`default_ttl_hours`	The default allocation lifetime, in hours, as configured server-side.

The Token alg KPI is the quickest check for the tokenless case described below: if it reads —, mints will return a join code but no signed token.

Mint a join code

The Mint allocation panel calls fleetGames.netcodeAllocations.mint({ orgId, namespace, maxPlayers, region }).

Field	Rules
Session namespace	Required. A session name, e.g. `season-3/match-118`. The platform scopes it to your organisation and returns `arena/<your-org-id>/<name>`, so you cannot name another tenant’s namespace.
Max players	Required integer, `1`–`1024`. The console’s bounds mirror the mint procedure’s own bounds.
Region	`auto` (default edge), `fra` (Frankfurt), or `sg` (Singapore).

The response is { code, token, tokenless }. On success the console shows a one-time banner with the join code and, when the org has a signing key, the host token:

Join code — shown once in the banner, but also recoverable later from the allocations table row.
Host token — shown once only. Copy it before dismissing the banner; the console does not re-display it, and there is no “show token” action on the table row.

The list and KPI queries are invalidated after a successful mint, so the new row appears immediately.

Host token issuance and signing keys

The host token is signed with the org’s active allocation signing key, published through the org’s JWKS. Key material lives on the API keys screen (fleetGames.netcodeSigningKeys), not on the Allocations screen. If the org has no signing key, minting still succeeds but the response comes back with tokenless: true and a null token. The banner then says:

Tokenless — create an allocation signing key in Developers to mint signed tokens.

To fix it, go to API keys → Token discovery (JWKS) and press Generate signing key (fleetGames.netcodeSigningKeys.create, which the console calls with alg: 'Ed25519'), then mint again. Existing tokenless allocations are not retro-signed; their join codes remain listed as-is.

Regions and the single-relay rule

Every peer on an allocation shares one relay. The PoPs are not meshed, so peers that land on different edges cannot see each other. That is why region is chosen at mint time and then fixed for the life of the allocation:

auto — the default edge.
fra — Frankfurt.
sg — Singapore.

Pick the region closest to the session’s players, and mint a separate allocation per session rather than reusing one across regions.

Redeem log and player caps

The Redeem log panel calls fleetGames.netcodeAllocations.redeemLog({ orgId, limit }) — the screen requests the 20 most recent redemptions. Each entry shows:

Column	Meaning
Code	The join code that was redeemed.
Peer	The peer id, truncated in the UI.
Reg	The region the redeem resolved to.
Result	A tick for a successful redeem, a cross otherwise.

Failed redeems appear here too, which makes this the first place to look when a client reports that a code did not work. The per-row Redeemed / Max players counter on the allocations table is the cap side of the same story: the max players value you set at mint time is what the counter is measured against.

Expiry, revoke and state

An allocation leaves the active set when it expires (the Expires column, driven by the default TTL shown in the KPI strip) or when you revoke it. Revoke calls fleetGames.netcodeAllocations.revoke({ orgId, id }). The action is rendered only while the row’s state is active; once the state is anything else, the button is gone and the row cannot be re-activated from the console. After a revoke the console invalidates the list and KPI queries, so the row’s state chip and the Active allocations count update together. Revoke is the only lifecycle control on this screen. There is no extend-TTL action and no per-peer disconnect action in the console.

Mint and revoke API keys

The API keys screen manages the bearer tokens used to call the allocation API (fleetGames.netcodeApiKeys).

Create — press Create key, give it a name (required, up to 80 characters, e.g. unity-client-prod), and submit. netcodeApiKeys.create({ orgId, name }) returns token_cleartext, which the console displays once in a banner: “copy your token now — it is shown only once”. Afterwards the table shows only a token_preview prefix.
Revoke — netcodeApiKeys.revoke({ orgId, id }). A revoked key keeps its row, dimmed, with a revoked chip in place of the Revoke button.

The table also shows the key’s creation date and Last used, which is blank (—) until the key has authenticated at least once — useful for confirming which key a client build is actually presenting.

Key scopes and environments

Each key row lists its scopes and its environment.

Column	What it shows
Scopes	The allocation-API capabilities the key carries — the console describes keys as scoped to allocate / join.
Env	`live` keys are chipped in the success tone; non-`live` (test) keys in the secondary tone.

Scopes and environment are properties of the key as returned by the list procedure; the console does not edit them after creation. To change either, create a new key and revoke the old one.

The relay allocation API

The Relay allocation API panel is a static reference table for the allocation endpoints, rendered from the screen’s endpoint list. For each endpoint it shows:

the HTTP method (POST endpoints are chipped in the success tone, others in the secondary tone),
the path, with a one-line note on what it does,
the request body and, below the arrow, the response shape.

Authenticate these calls with an API key from the table above, presented as a bearer token. Everything on this path rides QUIC/MoQT.

Token discovery and signing-key rotation

The Token discovery (JWKS) panel shows the JWKS URL for the org and the keys published at it (fleetGames.netcodeSigningKeys.jwks({ orgId })). The URL is copyable — point your verifier at it rather than pinning a key by value. Each key entry shows:

Field	Meaning
`kid`	Key id. This is the `kid` header on host tokens signed with it.
`alg`	Signing algorithm, with the curve appended when present.
Rotated	When the key was last rotated.
State	Key state chip, so you can tell the active key from older ones.

Generate signing key creates a new key for the org (the console requests Ed25519) and invalidates the JWKS query, so the new kid appears in the list. Verifiers that fetch the JWKS by URL pick up the new key without a code change; because tokens carry kid, tokens signed by an older key stay verifiable as long as that key is still published. With no keys at all, the panel reads “No signing keys — add one to mint signed allocation tokens”, which is the same condition that makes mints tokenless.

Endpoint discovery over a DNS HTTPS record

Clients do not hardcode a port. They discover the QUIC port from a DNS HTTPS resource record on arena.firstbyte.fast, which advertises:

Parameter	Value
`alpn`	`h3`
`port`	`4443`

There is no TCP fallback. A client that cannot resolve the HTTPS record, or that sits behind a network which blocks UDP, does not connect at all — it does not silently downgrade. Treat “no HTTPS RR” and “UDP blocked” as the two first hypotheses when a client never reaches the relay and nothing shows up in the redeem log.

Open a session from code

The API keys screen ships this snippet for a raw-QUIC session over the C FFI core. The bearer is an API key from the table above; the namespace is the same namespace you minted the allocation for.

// Rust — open a session and broadcast over the FFI core
use clutchcall::{Client, Role, Channel};

let net = Client::connect("arena.firstbyte.fast")
    .bearer(std::env::var("CLUTCHCALL_API_KEY")?)
    // the namespace the allocation returned — not one you invent
    .net_open(&allocation.session_namespace, Role::Server).await?;

net.on_peer(|peer, up| println!("peer {peer} {up}"));
net.send(/*peer=*/0, Channel::Reliable, &spawn_msg)?;   // 0 = broadcast

Notes on the shape of this API:

Role::Server opens the session as the host. The host is the party that holds the host token from the mint banner.
on_peer fires on peer join and leave — the up flag carries which.
send takes a peer id and a channel; peer id 0 means broadcast to every peer on the allocation. Channel::Reliable selects the reliable lane.

Authentication — API keys, token minting, and key rotation across the platform
Telemetry — metrics and traces for the QUIC data plane

Start here

Console

Guides

Reference

Console (allocations and join codes)

What an allocation is

KPIs on the allocations screen

Mint a join code

Host token issuance and signing keys

Regions and the single-relay rule

Redeem log and player caps

Expiry, revoke and state

Mint and revoke API keys

Key scopes and environments

The relay allocation API

Token discovery and signing-key rotation

Endpoint discovery over a DNS HTTPS record

Open a session from code

​What an allocation is

​KPIs on the allocations screen

​Mint a join code

​Host token issuance and signing keys

​Regions and the single-relay rule

​Redeem log and player caps

​Expiry, revoke and state

​Mint and revoke API keys

​Key scopes and environments

​The relay allocation API

​Token discovery and signing-key rotation

​Endpoint discovery over a DNS HTTPS record

​Open a session from code

​Related

What an allocation is

KPIs on the allocations screen

Mint a join code

Host token issuance and signing keys

Regions and the single-relay rule

Redeem log and player caps

Expiry, revoke and state

Mint and revoke API keys

Key scopes and environments

The relay allocation API

Token discovery and signing-key rotation

Endpoint discovery over a DNS HTTPS record

Open a session from code

Related