Check a game's key when a server starts

Call GET /developer/v1/key once as each Roblox server starts, confirm the key opens the right game, and handle a 401 or a 429 the way the platform expects.

Roblox games

A server that checks its key as it starts knows at once whether the platform will answer it, and says why in the log when it will not. This recipe calls GET /developer/v1/key once per server, compares the universe id it answers with game.GameId, stops on a 401 and waits out a 429. The route's answer is on GET /developer/v1/key.

Before you start

  • The game's key in the experience's secret BlockoutApiKey, with the domain studio.blockoutgames.com, and Allow HTTP Requests on. See Getting a game's API key.

  • For the Template: platform = true in the game's Config/Overrides/Features.luau. For any other game: nothing else.

Steps

  1. Add a check that runs once per server

    In the Template, a server service whose start() calls PlatformService.key(). Elsewhere, one function run from a server script with task.spawn. Never call it from init() or from code a player waits on: it yields.

  2. Compare the universe id

    The answer's game.id is a universe id, as game.GameId is in the server. When they differ, the secret holds another game's key, and its requests count against that game.

  3. On 401, stop

    The key is missing, wrong or revoked, or its game left the studio's catalog. Do not retry: log once, and update the secret.

  4. On 429, wait Retry-After

    Wait the whole seconds in the Retry-After header, then send the same request once more.

  5. On 5xx or no answer, back off

    Wait 1 second, then 2, and give up after three tries; the game plays on without the platform.

PlatformService already retries: a 429 after its Retry-After (giving up as rate_limited when it asks for more than 30 seconds), a 5xx or no answer after 1 and 2 seconds. A 401 is unauthorized and is never retried.

src/main/server/Services/KeyCheckService.luau
--!strictlocal PlatformService = require(script.Parent.Parent.Parent.Services.PlatformService)local KeyCheckService = {}-- Skipped by the Loader while Config/Features.platform is off.KeyCheckService.feature = "platform"function KeyCheckService.start()	local info = PlatformService.key()	if not info.ok then		if info.reason == "unauthorized" then			warn("[KeyCheck] 401: the key was refused. Update the BlockoutApiKey secret.")		elseif info.reason == "rate_limited" then			warn("[KeyCheck] 429: this key is over its limit. Something asks too often.")		else			-- unavailable (no secret), unreachable (HTTP off), platform_down, busy, ...			warn(`[KeyCheck] {info.reason}: {info.detail or ""}`)		end		return	end	local key = info.value.value	if info.value.stale then		warn(`[KeyCheck] the platform did not answer; using a check from {os.time() - info.value.storedAt} s ago`)	end	if key.game.id ~= game.GameId then		warn(`[KeyCheck] this key belongs to {key.game.name} ({key.game.id}), not this game`)		return	end	print(`[KeyCheck] {key.game.name}: {key.limits.perMinute} requests a minute`)endreturn KeyCheckService

Try the request with curl first

Shell
curl -s -i https://studio.blockoutgames.com/developer/v1/key \  -H "Authorization: Bearer $BLOCKOUT_API_KEY"

-i shows the status line and Retry-After. Keep the key in an environment variable, never in a file you commit.

What it costs the key

One request per check. Through the Template's shared cache the answer is kept 30 minutes, so every server starting in that time shares one request. A raw HttpService check costs one request per server start.

What you get

A line in each server's log that names the game and its limit, or says exactly why the platform will not answer: no secret, a refused key, a key from another game, a key over its limit, or no answer at all.

Updated