The API has three ways of knowing who is asking. A person in the panel carries a session from GitHub sign-in. The assistant app reads as that person with a short-lived signed assertion the API gave it. A game's Roblox servers send the game's API key. Each route accepts exactly one of the three, and every rule about a person applies the same whichever way their request came. The member-facing summary is Security and privacy.
The three ways a request is identified
| Caller | Sends | Accepted on |
|---|---|---|
| A person | The session cookie | Every /v1 route their role allows |
| The assistant app | x-blockout-assertion and a signature | Only GET routes on the assistant's read list |
| A game's servers | Authorization: Bearer bk_live_… | Only /developer/v1/* routes |
GitHub sign-in
Sign-in runs on better-auth inside the API (apps/api/src/modules/auth); the panel forwards /auth/* to it under its own address. The GitHub app asks only for read:org, every sign-in uses PKCE and a single-use state stored hashed and bound to the browser by a signed cookie, and the person is admitted only if GitHub says their membership of BlockoutGames is active. The steps are drawn in How sign-in works.
- Admitted
An active member of the organization. A GitHub organization
adminbecomes anowner; anyone else amember.- Sent to the website
Someone outside the organization, or with only a pending invitation, goes to
www.blockoutgames.com/?notice=developers-only. Three such refusals from one address in 15 minutes hold that address's sign-ins back until the window passes.- Sent to the sign-in page
Every other refusal (
unavailable,invalid,expired,cancelled,rate-limited) lands on/sign-inwith a sentence and a retry button; nothing starts another sign-in by itself.
Sessions: the cookie, its lifetime and its end
A session is 32 random characters in a signed cookie: __Host-scrywave_session over HTTPS, HttpOnly, Secure, SameSite=Lax. The database and Redis store only h1: and its SHA-256, so a copy of either opens nothing. The lookup behind each request is cached in Redis for at most 60 seconds, and every change to a session clears its entry.
- Idle lifetimedays
30 from the last extension; extended at most once an hour.
- Absolute lifetimedays
90 from sign-in, however often it is used.
- Rotation
Every sign-in issues a new token and ends the browser's previous session; if the role changed, every other session ends too.
- Ending
Settings, Sessions: end one, end all others, or sign out everywhere. Owners can end a member's sessions from Admin, which the audit log records with the owner's name.
How membership is kept current
No request waits on GitHub. Every 60 seconds one copy of the API (holding a Redis lock) asks GitHub, with each person's own stored token, about everyone with a live session whose last confirmation is more than 5 minutes old.
- Still a member
The confirmation moves forward.
- Left, or revoked the app
Every session of theirs ends at once.
- Promoted or demoted
The new role is recorded and every session ends, so the next sign-in carries it: permissions never change under a running session.
- GitHub unreachable
Nothing changes for 30 minutes after the last confirmation; past that, requests answer 401
unverifiedand the next page load signs in again.
A removal reaches every session within about 5 minutes plus a minute. It costs one GitHub call per signed-in person per 5 minutes, on their own token's allowance.
How the API checks every request
Cross-site changes are refused
A POST, PUT, PATCH or DELETE the browser marks
Sec-Fetch-Site: cross-site, or whoseOriginis not the panel's, is 403.The session is resolved
One Redis or Postgres read finds the session and the person, checks the absolute lifetime and the membership standing. Anything wrong is 401, with
reasonwhen a session ended.Changes need the panel's header
A change without
x-requested-with: scrywave, which a cross-site form cannot send, is 403.Owner-only routes refuse members
A route marked
@OwnersOnly()is 403 for a member, before its input is read.Rate limits are counted
Per person and per address; see API rate limits.
The record's own rules apply
A use case checks the rule about the particular record (below), so another person's record answers 404, never theirs.
Roles and who may do what
There are two roles, both from GitHub: owner and member. Roles are never edited in the panel. Within a studio game there are two more parts, which come from the studio's records: its lead (named on the game) and its crew (its project's developers and its lead). See Roles.
| Who | May |
|---|---|
| Any member | Read every market, studio and code page; their own watchlist, home, notifications, sessions, points |
| Lead | Change their game's details and release log |
| Crew | Create, rotate and revoke their game's API key; read and triage its player feedback |
| Developers | Correct and submit their project's contract, and sign it |
| Owner | Everything above for every game, plus Admin: groups and keys, members and sessions, audit, data health |
Nobody changes a contract once approved, and a game's developers never buy its shares. A test reads every route's rule from the controllers and fails when they differ from the API's documented table.
The assistant's assertion: reading as the person who asked
The assistant app has no session and no database. When you ask a question, the API vouches for you with an assertion signed by a secret only the API holds (API_ASSERTION_SECRET), and the assistant sends it back with every read it makes, each read signed with the secret the API and the assistant app share (AI_SERVICE_SECRET). The assistant app can read the assertion but not make one, so it can only ever read as someone who asked it.
- Assertion
v1.<payload>.<signature>: the payload holds your user id, role, the request id and its times; the signature is HMAC-SHA256 over it. It lives 180 seconds (an answer is bounded at 90), none is honoured past 300, and it is checked in constant time.- Request signature
On every request from the API to the assistant app: HMAC-SHA256 over the assertion, the method, the path and the body's hash. An assertion the assistant sends back with a read therefore cannot start an answer.
- Accepted for
Only a
GETof a route onASSISTANT_READ_ROUTES, as you, with your rate limits. Any write, owner or admin route, key route, settings or sign-in route is 403; a bad or expired assertion is 401.
What the assistant can read is listed in The assistant.
Game API keys versus sessions
A game's Roblox servers cannot sign in, so they use the game's platform key (bk_live_ and 43 random characters), created by the game's crew on its Developer tab and stored only as its SHA-256 hash and last four characters. Key routes (/developer/v1/*) accept the key and nothing else; session routes never accept a key.
- Looked up
On every request, uncached, so a rotated or revoked key stops at once.
- Limits
120 requests a minute per key, 1,200 for every key together.
- Reaches
Its own game's feedback, and the stored market data the panel shows. Never Roblox: an untracked game is 404.
- Refused
The same 401 whatever was wrong, never repeating the key; also when its game has left the catalog.
See Keeping a game's key secret and the developer API.
Configuration
| Variable | Default | Meaning |
|---|---|---|
BETTER_AUTH_SECRET | — | Signs session cookies, encrypts stored GitHub tokens |
AUTH_MEMBERSHIP_INTERVAL_MINUTES | 5 | How old a confirmation may get before GitHub is asked |
AUTH_MEMBERSHIP_GRACE_MINUTES | 30 | How long the last confirmation stands while GitHub is down |
AUTH_REFUSED_SIGN_IN_LIMIT | 3 | Outsider refusals per address in 15 minutes |
AUTH_AUDIT_RETENTION_DAYS | 180 | How long the audit log keeps sign-in entries |
AI_SERVICE_SECRET | — | Signs requests to and reads from the assistant app |
API_ASSERTION_SECRET | — | The API's own: signs the assistant's assertions |
The API refuses to start if either equals another of its secrets or a credential root key.
Related: Security and privacy, API and caching, The assistant.
Updated