Roles and actions: the full matrix

Français · Type: reference · Audience: author, admin · Context: hosted Studio · Status: ready · Applies from: 4.4.0

The Studio Server (hosted team Studio) · contract: experimental · verified by CI (support matrix of 4.4.0, 2026-10-23): Postgres, S3 and Keycloak in CI; Chromium and Firefox (job studio-hosted); WebKit on macOS, by hand only · automated checks: jobs studio-hosted, studio-install-smoke; CI plan studioHosted; 3 test files · people's passes: studio-hosted not run (#149), studio-collab not run (#150), studio-preview not run (#166), studio-assets-hosted not run (#167), studio-mcp-remote not run (#196), studio-oidc-generic not run (#197) · known limits: roles-fixed

On a team Studio every member has one role: owner, dev or reviewer. This page lists every route of the Studio Server and the role it needs, read from the code: the gate (auth/gate.ts), the role of each API route (roleFor in http.ts), the owner's routes (auth/routes.ts) and the API's table (ops/routes.ts).

How to read it

• The roles are ranked: reviewer < dev < owner. A route that needs dev is open to owners too.
• The rule: a GET (and a POST that only reads, such as a check) needs a reviewer; any other write needs a dev; the members, the invitations, the audit and a few whole-game actions need an owner. The exceptions are listed in each table.
• Below the role a route needs, the answer is 403 this needs the role <role>. A logged-in person who is not a member gets 403 not a member of this project. Without a session or a token: 401.
• The role is checked on every request, with the session cookie (the browser) or a Bearer access token (the CLI, scripts, the MCP). A role changed or a member removed takes effect at their next request.
• The routes below are under the Studio's public URL. The game's origin (playUrl) has its own rules, at the end.

owner

Everything a dev may do, plus: the members, their roles and sessions, invitations, the audit log; taking a span over; the exclusive lease by hand; Git push and import; the engine's upgrade; a fresh rebuild of a published build; bringing the notes in as comments; cancelling anyone's job. The last owner can be neither demoted nor removed.

dev

Writes the game, span by span: rooms, texts, values, the storyboard, the map's groupings, notes, voices, uploads and cuts, Prepare, undo and redo of their own operations, publishing a build, asking for a bisection, taking and releasing spans. Resolves any comment thread. Cancels the jobs they started.

reviewer

Reads and plays: every read of the game and of the Studio, the checks (validator, solver, lint…), the previews and builds, the live stream. Writes no game file. Comments, edits their own comments, and resolves their own threads. Holds no lease.

The game: reads and edits

Checks and history

These POSTs only read: they take their options in a body, need no lease, and are never refused for a span.

Live, presence and spans

Comments

Only its author changes a comment's text, whatever their role (403 otherwise). There is no route to delete a comment.

Assets, jobs and builds

Members, Git and the engine

See Managing members, The game in Git and Upgrading the engine of a hosted game.

The remote MCP

POST /mcp takes a Bearer access token only (never the session cookie), from a member: a reviewer at least. Each tool is then a request to the same /api with the caller's token, so a tool needs the role of its route: a reviewer's agent reads and checks, a dev's agent writes. See Remote MCP.

Routes without a role

Every /auth/… route takes 30 requests a minute per address at most; past that it answers 429 with Retry-After: 60.

The game's origin

On playUrl no Studio API and no /auth route answer. Every path needs a game session, made from a ticket that a member's browser session asked for (POST /api/play-ticket): any role. The game session lasts 15 minutes, sliding, and is checked at every request against the member's Studio session and membership. With publicBuilds: true in the configuration, /play/… and /icons/… (the published builds) open without a session, to anyone.

Refusals that are not about roles

Even with the right role, a write can be refused:

• 423: the span is held by someone else, or the whole game is (423).
• 409: the file changed since you read it (409), or the last owner would be demoted or removed.
• 403 forbidden: a browser write without the exact Origin, the header X-Studio-Request: 1 and a JSON body.
• 503 with Retry-After: the instance does not serve writes yet (a redeploy), or the identity provider has not confirmed your session for 15 minutes (suspended).
• 429: too many refused authentications from one address in a minute (30), or a busy job queue.

Guarantee · roles-read-review-write-dev · referenced · executed on aff6caab7514 · scope self-checked by the author (AI), not reviewed Every route of the Studio API's table needs a reviewer when it only reads (a GET, or one of the read-only POSTs) and a dev otherwise; the test walks the whole table.

Limit · roles-fixed The three roles are fixed: there is no custom role, no per-room right, and no read-only dev. A provider's groups give no right.

Related identifiers

• Managing members, Invitations.
• Concepts: spans, leases, the exclusive lease.
• ADR 0027: the four HTTP policies.

Edit the source of this page · Report an error