API keys

Two directions

Confusing these is the expensive mistake, so Rostack keeps them visibly apart. Both appear on the same page precisely so that the difference is stated once rather than discovered later.

Issuing a key

Using a key

Send it as a bearer token. One key authenticates every endpoint, so a service that reports activity and also changes ranks needs one key, not two.

# The same key authenticates every endpoint.
curl -X POST https://rostack.app/api/v1/rank \
  -H "Authorization: Bearer rsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"robloxUserId": 1234567, "rank": 50, "reason": "Reached 100 points"}'

The gate

Every request authenticated by an API key passes through one piece of code. The header is parsed one way, the key is resolved through one cache, and every failure returns one indistinguishable answer. An endpoint does not get to authenticate slightly differently, because the gate is how a handler receives its key at all.

That last point is the security argument rather than a tidiness one. Every authentication failure answers identically, whether the key never existed, was revoked an hour ago, or was mistyped:

{
  "error": "unauthorized",
  "message": "Invalid or revoked API key."
}

Distinguishing them would let somebody probe which keys once existed. Rejections are cached briefly too, so timing does not give away what the message withholds.

The rank ceiling

Every key carries a maximum rank and can never assign at or above it, however it is used. A key is a machine actor with no human behind it, so it gets an explicit limit rather than inheriting whatever its creator could do. A game-server key lives somewhere a game server can read it, which is to say somewhere that leaks, and a leaked key must not be able to create an administrator.

The ceiling is also capped at the rank of the person issuing it. Without that, a low-ranked seat holding ranking.run could mint a key at 254, call the API with it, and promote themselves past the rank ceiling every other check depends on. A key is never a ladder out of your own rank.

Ranks that a Rostack role is mapped to are refused outright to a key, with role_overreach. Moving somebody into such a rank hands them Rostack permissions, and a key holds a rank ceiling and no permissions of its own, so there is nothing to check it against. Those moves are made by a person, from the dashboard, under their name.

Revoking

Revoke on the API keys page. Because every endpoint authenticates through the same gate, revoking stops the key everywhere at once rather than on the endpoint you were thinking about.

The Open Cloud key

The other direction. This is the key Roblox issues to you, that Rostack uses to write ranks on your behalf. Reading your group is public; writing a rank is not.

Rostack encrypts it with Cloud KMS and stores only the ciphertext. It is never sent anywhere but Roblox, never shown back to you, and never written to a log. Connecting one is an owner-level act rather than a staff one.