Developer portal keys page

Purpose

The signed-in page where a developer mints, sees and revokes the API keys that reach the gateway: a name field that produces one ai-scoped key shown once, a list that shows prefixes only, and a "Sperren" that takes effect at once. The invariant that makes it trustworthy is that the HTML carries no account data and the browser never holds a customer key: the page ships as a shell whose branches are hidden by CSS until the server has answered, a freshly minted key is written into exactly one node and cleared by the button that dismisses it, and the list can only ever show what the server stores, which is the first twelve characters and a hash.

It makes two backend modules visible: B10 (GET, POST and DELETE /api/developer/keys, the ai-only rule for a Prima surface, the once-only key in the POST response) and B11 (the key a customer copies here is the credential the gateway's local door accepts as X-API-Key; the page's own per-session key is the same kind of credential, minted for the meter and revoked at sign-out).

When to use

Trigger phrases: "the keys page", "Schlüssel ausstellen", "why does the list show only a prefix", "the key is gone after reload", "Sperren", "the portal's own session key in my list", "noch nicht freigeschaltet", "which workspace does the key bill". Surface: portal, the static Astro site of F7 after sign-in; the same origin, the same sessionStorage session, the shell chrome of Layout.astro and the signed-in sub-navigation of AppNav.astro (src/components/AppNav.astro lines 9 to 15: Schlüssel, Verbrauch, Guthaben, Ausgabenlimit, Playground). It is a static shell rather than a server-rendered page because the site has no server: the guard is a convenience, and the authorisation runs on every call (schluessel.astro lines 9 to 14).

Do not use it for the Labs SPA's key settings (identity-auth/ui/api-keys-settings-and-developer-dashboard, F3: React, every self-service scope, the developer dashboard), for the pages that show money (/verbrauch, /konto/guthaben/, /limit: billing rows; the "Guthaben" button here only links there, and the owner-or-admin rule for changing a billing instruction, A-1, lives in billingWriteAccess, prima-api.ts 655 to 665, not on this page), or for the sign-in pages that precede it (F7).

Stack assumptions

S1 in the demo only: the page reads the portal's house variables through app.css (src/styles/app.css, 867 lines, "No new colours, no new fonts", lines 1 to 4) and the demo maps them onto @prima-modules/prima-tokens (Frontend). S3 for the site shape. No S2: nothing is React; the page is markup plus one module script of 318 lines (schluessel.astro 314 to 632).

Component library: none; AppNav.astro is the one shared component. Data-fetch style: prima-api.ts request() on the session (Authorization: Bearer from authHeader(), X-Prima-Surface: prima_dev, X-Workspace-ID when the page has one, credentials: "omit"; lines 335 to 346 and 401 to 443); every failure is an ApiError with status, code, detail and the raw gatewayCode (214 to 257) and every rendered sentence comes from errorMessage (282 to 322). Copy: de-CH, Sie-Form, no ß; dates through Intl.DateTimeFormat("de-CH") (formatDate, 1428 to 1432). Env: PUBLIC_PRIMA_API_BASE baked at build as in F7; unset, the page builds and its script lands in the notconfigured branch (prima-api.ts 336 to 338, schluessel.astro 617).

Data model

Client state, in the DOM's data-state attributes and one module variable:

The convention is app.css lines 105 to 122: [data-when] { display: none } and one rule per state that shows the matching child, so exactly one branch of a container is visible and a state the script never sets shows nothing.

Types consumed (prima-api.ts):

interface Account { id: string; email: string; first_name?: string | null; last_name?: string | null; company?: string | null; role?: string | null; surfaces?: string[] }   // 464 to 474
interface Workspace { id: string; name: string; slug: string | null; role: string; isOwner: boolean }   // 617 to 623
interface ApiKeySummary { id: string; key?: string | null; key_prefix: string; name: string; description?: string | null;
  created_at: string; expires_at?: string | null; last_used_at?: string | null; is_active: boolean; scopes?: string[] | null }   // 914 to 926; `key` only in the POST response

Browser storage read or written on this page (all sessionStorage, F7's Data model has the full table): prima.dev.session.v1 (read by requireSession; cleared and the page left for /anmelden/ when missing, expired or refused with 401); prima.dev.gateway-key.v1 (the per-session ai key: {id, key, prefix, tenantId, sid, mintedAt}, gateway-key.ts 218 to 230, minted on first need by ensureGatewayKey, prima-api.ts 687 to 708, or already present from the verify page); prima.dev.gateway-key.retired.v1 (row ids parked for the next revoke, never a key); prima.dev.gateway-key.housekept.v1 (the sid whose sign-in housekeeping ran, auth.ts 847 to 866). A customer's key minted on this page is never stored anywhere in the browser: it lives in #reveal-key's text until "Ich habe ihn gesichert", a new mint or unload (INVARIANT B, prima-api.ts 29 to 35).

API surface

All on the session Bearer; the backend side is B10, with B15 for the workspace listing:

Error bodies: four shapes reach this client (the OpenAI envelope from Prima and from Labs' gateway handler, Labs' plain handler, FastAPI's default) and parseErrorEnvelope in billing.ts reads all of them so a test can pin it (send, 426 to 439). No WebSocket, no postMessage. The page reads nothing from the meter: the tenant comes from the key record, not from /usage (Gotchas).

Application logic

1. The page ships with #gate[data-state=loading], the whoami skeleton and every branch in the HTML; the module script runs boot() (schluessel.astro 604 to 622, 631).
2. requireSession() (prima-api.ts 507 to 546): not_configured throws before any read; no local session or one past expiresAt is redirectToSignIn() (clears the session, location.replace('/anmelden/'), throws so nothing runs behind the navigation, 476 to 481); GET /api/auth/me; a 401 clears the stale token and redirects the same way; surfaces present without prima_dev throws 403. On a good answer the per-session key's lifecycle is armed (armSessionEndRevoke, 837 to 855: a revoke scheduled before the Bearer dies) and the sign-in housekeeping runs once per sid in the background (sessionKeyHousekeeping, 882 to 908: revoke the parked ids, then list the tenant's keys and revoke this portal's orphaned rows).
3. boot's catch (613 to 621): unauthenticated returns (the page is leaving); forbidden sets denied; not_configured sets notconfigured; everything else sets error with errorMessage(err) in #gate-err, and #gate-retry calls boot() again (624).
4. renderIdentity(me) (591 to 602): displayName (first and last name, else the e-mail, 580 to 583) in bold, the e-mail after a middle dot when it differs, and #kh-actions unhidden.
5. resolveWorkspace() (360 to 379): workspaceId = await resolveTenantId(), which is ensureGatewayKey().tenantId (634 to 636): the record from sessionStorage when it is for this sid and not near expiry, else one mint (GET /api/auth/workspaces, chooseTenant, POST /api/developer/keys, acceptMintedKey, saveGatewayKey; 687 to 744, single-flight through the minting promise). Then, cosmetically, the workspace name from listWorkspaces(); #ws-single reads "Workspace: . Der Verbrauch dieses Schlüssels wird ihm zugerechnet." A failure of the name lookup never blocks minting (363 to 371).
6. #gate becomes ready; wireCreate() binds the form, the reveal's copy and close buttons and the beforeunload guard (507 to 588); loadKeys() runs without being awaited (612).
7. loadKeys (441 to 458): #list-card to loading; listKeys(workspaceId); an empty array is empty; otherwise #key-rows is emptied and one keyRow appended per key (382 to 439: title, the meta line "prefix · erstellt · zuletzt genutzt or noch nie genutzt · läuft ab · dieses Portal, diese Sitzung: wird beim Abmelden gesperrt" when isSessionKey(k), the chip--live or chip--off chip, and "Sperren" for an active key); ready. A refusal goes through failCard.
8. Submit (513 to 560): the field error cleared; an empty name is "Bitte geben Sie dem Schlüssel einen Namen." with focus; no workspaceId is "Kein Workspace ausgewählt."; hideReveal() first (a previous key leaves the DOM before a new one arrives); the button disabled and #create-state reads "wird ausgestellt …"; createKey(name, workspaceId); on a body with key, showReveal(key) (textContent into #reveal-key, panel shown, the key node focused so a keyboard user lands on the thing to copy); on a body without one, the card's error branch; then loadKeys(); on a thrown forbidden the server's detail under the field, otherwise failCard; the button re-enabled in finally.
9. Copy (564 to 577): navigator.clipboard.writeText, "Kopiert" with data-copied, or the honest "Nicht möglich, bitte markieren und kopieren". "Ich habe ihn gesichert" (hideReveal, 495 to 505) clears #reveal-key, hides the panel and resets the copy button. beforeunload (581 to 587) warns while the panel is visible.
10. Revoke (461 to 482): a native confirm() naming the key and saying it stops at once, everything using it gets 401, and it cannot be undone ("a custom dialog here would be more design and less certainty", 462 to 463); the button reads "Wird gesperrt …"; revokeKey(id, workspaceId); loadKeys(); on failure the button is restored and the list card shows the error.
11. "Abmelden" (signOut, 557 to 578): revoke the per-session key and the parked ids (revokeSessionKeys, 802 to 835), clear the local session, POST /api/auth/logout best-effort, location.replace('/anmelden/').

Invariants

• No account data in the HTML: the shell's branches are hidden by CSS and the HTML contains no name, e-mail, prefix or id until the script writes them (schluessel.astro 9 to 14; Acceptance check 3).
• A customer key is rendered into exactly one node (#reveal-key) by textContent, cleared by hideReveal before any new mint and on "Ich habe ihn gesichert", never stored, never in the URL (16 to 21, 485 to 505, 528).
• The page never issues a key without scopes: ["ai"] and never with any other scope (createKey 949 to 954; gatewayKeyMintBody gateway-key.ts 110 to 122); a minted key that comes back with another scope is revoked before it is kept (acceptMintedKey, prima-api.ts 729 to 733).
• Key management runs on the session Bearer, never on an API key: an ai key is prefix-locked to /api/prima/v1/ and answers 403 on /api/developer/keys (prima-api.ts 99 to 103; S5 prefix lock), so a key that could mint keys does not exist.
• The list shows prefixes only because the server stores prefixes only (keyRow 403, B10 Data model).
• The guard's three denials stay apart: no session redirects, a 401 redirects after clearing, a missing prima_dev grant stays put and says so, because signing in again cannot add a grant (requireSession docstring 490 to 500).
• Revocation is confirmed in words that name the consequence, is instant and irreversible on the server (soft delete, B10), and the list is re-read from the server afterwards rather than patched locally (473 to 475).
• Every X-Workspace-ID the page sends is the tenant Labs validated at the per-session mint (resolveTenantId 629 to 636); the browser never picks a tenant from a list when there is more than one (chooseTenant).

Frontend

The rendering is the live rebuild developer-portal-keys-page/demo.astro, rendered by the docs host as one frame per state (RENDERING.md, section 3). One Astro component takes state and renders the shell with the data-state attributes the module script would have set and the rows it would have appended, from literal sample data: the docs page shows every branch at once and nothing reaches the network. hydrate: only describes the real page (a shell; the visible branch is the script's decision after the guard); the docs host renders an Astro demo server-side and reads no hydrate key for it (prima.li/src/index-site/DemoIsland.astro at 86fe9d1, lines 131 and 136).

Every state declares viewport: 1440: the page is shell-wrapped (the site header from Layout.astro 51 to 77, the slate band, the signed-in sub-navigation from AppNav.astro), so the docs host lays the frame out at the portal's desktop width and scales it into the column (DemoFrame.astro at 86fe9d1, the demo-stage--viewport branch). Heights are minimum heights per state, from 700 px for the gate states to 1700 px for the reveal: the host writes height as min-height on .demo-viewport (DemoFrame.astro line 28) and the stage grows with the content, so a ready state taller than its floor is not clipped. Until the host's cascade is fixed (Gotchas, demo-frame.css lines 79 and 81), every one of these frames is inset by the stage's 24 px left padding and its right 24 px sit behind a sideways scroll on the docs page.

States, in order: default (gate ready: the identity line, the create form with the workspace sentence, three keys in the list with the portal's own session key first and marked "dieses Portal, diese Sitzung: wird beim Abmelden gesperrt", one revoked key with the Gesperrt chip and no "Sperren", and the housekeeping card), loading (the whoami skeleton in the band, the gate skeleton card, no sub-navigation), empty (no keys yet: the dashed empty state with "Zum Schnellstart"), revealed (a mint just succeeded: the reveal with an obviously fake key in one node, "Kopieren" and "Ich habe ihn gesichert", and the list with the new row on top), create-refused (a 403 on the mint: the server's own sentence under the name field, the typed name still in the field), list-error (the list card's error notice with the server sentence and "Erneut versuchen", the create form intact), unavailable (GET /keys answering 404 with a session key already in sessionStorage, then a mint refused with 404: both cards show the quiet "noch nicht freigeschaltet" notice, no error styling; a composite, because the list card goes quiet at load and the create card only after a submit, and without a stored key a 404 on the mint never reaches ready at all, Gotchas), denied (signed in, prima_dev not granted: the amber notice, the band skeleton still in place, no "Abmelden", no sub-navigation, no redirect, because requireSession throws before boot reaches renderIdentity), gate-error (the gate could not load: the red notice with the network sentence and a retry), unconfigured (built without the API base: the amber notice naming a configuration fault on our side).

Design system prima (D1b): the demo redraws app.css and the layout's nav with @prima-modules/prima-tokens aliases. The mapping, portal variable to token: --sand (page) to --bg-page; --sand-deep (skeletons, quiet notice, chips off) to --bg-surface; --slate (the band) to --bg-dark; --on-slate to --fg-on-dark; --on-slate-60 and --slate-line to white at 60 % and 14 % (no token); --line to --border-default; --line-strong to --border-strong; --purple to --fg-accent; --purple-50 and --purple-100 to a color-mix of the accent; --ink to --fg-default; --ink-60 to --fg-muted; --ink-30 to a color-mix of --fg-default into the page; --r-xl (cards) to --radius, --r-md, --r-lg and --r-sm to --radius-sm; --s-3 to --s-9 to --space-sm through --space-4xl; --font-display to --font-body at weight 500; --mono to --work-mono. The notice palette (.note--err #FDF0EF on #7C2B26, .note--warn #FBF0DC on #6E4E12, app.css 164 to 173), the chip green (--ok, --ok-bg) and the refusal red (--swiss) have no token; the demo declares them once on its root (Gotchas). The skeleton shimmer animation is not reproduced: the demo's skeleton is the static gradient.

Text and headings inside the demo are div and h3, inline code is span.mono, because the docs host's shell rules reach p, h1, h2 and code inside a frame at a specificity an Astro scoped rule cannot beat (prima.li/src/index-site/demo-frame.css at 86fe9d1, lines 147 to 169); the real page uses h1, h2, p and code.

Responsive: the band's row wraps its actions under the title, the card heads wrap, a key row wraps its tail under the meta line below about 500 px (.row is flex-wrap: wrap, app.css 301 to 309), and the site header collapses its links below 900 px keeping "Anmelden" (Layout.astro 168 to 175). Loading is the two skeletons (band and card), empty is the dashed card, error is the red notice with a retry per card, and unavailable is deliberately not an error.

What the demo deliberately does not render: the footer, the noscript block, the native confirm(), the beforeunload guard, the "Wird gesperrt …" and "wird ausgestellt …" pending labels, the focus moves, the sign-out navigation, and the skeleton animation. The copy is the page's own with the source's em dashes replaced by a colon or a full stop (house rule); names, ids, prefixes and dates are placeholders.

Security & tenancy

What the browser may hold: the session token and the portal's own ai key in sessionStorage (F7 Security & tenancy; auth.ts 665 to 702 says why the key is a smaller exposure than the token beside it: ai only, so it cannot list, mint or revoke keys, and it is revocable from this very list), plus parked row ids. Never a customer key beyond the reveal, never a refresh token, never a password. The portal's key is bounded on the server too: expires_in_days: 1 at the mint (gateway-key.ts 99 to 100), revoked at sign-out, at session end while the Bearer is still valid, and by the next sign-in's housekeeping for a tab that closed without either (prima-api.ts 127 to 136).

Origin and CSRF: credentials: "omit" on every call, the Labs CORS list carries the surface origin explicitly (F7). Nothing is a cookie, so there is no CSRF surface; the Bearer is attached by the script only.

Surface gating: X-Prima-Surface: prima_dev on every call; /me.surfaces decides the denied branch on the client, and the router mount decides on the server (B4). What is hidden by CSS: every branch of the shell, as a rendering convention, never as access control; the data a branch shows arrives only after the server has said yes. What is enforced: the Bearer on every read and write, the workspace membership at the mint (Labs re-checks it, 403), the ai-only rule for a Prima surface (B10, 113 to 126), the prefix lock that keeps an ai key off this page's routes (S5).

Attacker-controlled inputs rendered: key names (textContent in keyRow), server detail strings (textContent through setText), the workspace name (textContent). The page writes no innerHTML.

Tests

• prima-developer at c594dfc: npm test (node --test, 173 tests, 30 suites, all passing on 2026-09-12) covers the pure decisions this page relies on: gateway-key.test.ts (chooseTenant, gatewayKeyMintBody, acceptMintedKey, keyRefusalPolicy, orphanedPortalKeys, readGatewayKeyRecord), billing.test.ts (parseErrorEnvelope for the four error shapes, billingErrorMessage, mayManageBilling), desktop-auth.test.ts. The page script itself has no test.
• What a new app adds: a node --test table for classify (401, 402, 403, 404, 501, 429 with and without spend_cap_exceeded, 503 with and without credits_unavailable, 5xx) and for errorMessage on each code; a jsdom test of the shell that sets each data-state and asserts exactly one [data-when] child is visible per container.
• Playwright, against dist/ served statically with the API mocked: (a) no session, open /schluessel/, assert the navigation to /anmelden/; (b) a session in sessionStorage, /me mocked with surfaces: ["prima_web"], assert the denied notice, #whoami still the skeleton, #kh-actions still hidden, and no redirect; (c) /me ok, /workspaces with one row, /keys mocked [], assert the empty state; (d) POST /keys mocked 200 with key, assert one element holds it, sessionStorage does not, "Ich habe ihn gesichert" empties it; (e) DELETE mocked 200 and the list re-fetched (two GET /keys calls); (f) prima.dev.gateway-key.v1 seeded for the session's sid, GET /keys mocked 404, assert the list card's quiet notice at load; submit a name with POST /keys mocked 404, assert the create card's quiet notice and no red; without the seeded record, assert the gate's error branch instead.
• The kit's gate: npm run check prints no line for this recipe; the render smoke covers React demos only; the docs build is the render check for an Astro demo (Acceptance check 6).

Deploy & ops

Build target and deploy path as F7: Astro static, PUBLIC_PRIMA_API_BASE baked at build with PRIMA_REQUIRE_API_BASE=1 on a release build, S13's static portal ship (build, refuse a localhost or staging host in dist/, back up, rsync), rollback the printed rsync. CORS: the API side lists the surface origin. CSP: none of the portal's own at c594dfc. Ingress: GET, POST and DELETE /api/developer/keys* and GET /api/auth/workspaces must pass the API host's allow-list to Labs (measured 2026-09-11 in prima-api.ts 604 to 609 for the workspaces route; /api/auth/logout does not pass it, F7 Gotchas). Argus: none for this page; the check that matters is B12's outbox (a key minted here that Prima never learns about answers 401 at the gateway with no symptom on this page).

Gotchas

• 2026-09-12 (measured at c594dfc, prima-api.ts 590 to 636; corrects the inventory row F8, which says the tenant is "resolved from the meter (X-Workspace-ID from /usage)"): the tenant is no longer read back from /usage. Prima refuses a Labs session Bearer on /usage (503 identity_provider_unavailable, 600 to 603) and the meter now runs on the per-session key, whose tenant must be known before the mint; so the tenant comes from GET /api/auth/workspaces (the caller's own memberships, the predicate Labs uses to authorise the mint) through chooseTenant, and resolveTenantId returns the key record's tenantId with no network call once the key exists. The row's description was true of the build before A-2 (a), decided 2026-09-11.
• 2026-09-12 (measured at c594dfc, schluessel.astro 539 to 547 and app.css 105 to 122; D8, a verified defect recorded here and not fixed in this wave): when the mint answers 200 without a key, the page sets #new-card to error, and the state machine hides the ready branch, which holds the form. The card has no retry control (#gate-retry and [data-retry=keys] serve the other two containers), so the only way back to the form is a reload. The sentence tells the customer to revoke the key below and mint a new one, which they cannot do from this state. Fix it needs: render that failure into #key-name-err (as the 403 branch does) or add a retry to the create card's error branch.
• 2026-09-12 (measured at c594dfc, prima-api.ts 538 to 545 and schluessel.astro 591 to 622; D8, a verified defect recorded here and not fixed in this wave): requireSession throws the 403 forbidden before it returns me, so boot never reaches renderIdentity for a denied account: #whoami keeps the loading skeleton for good and #kh-actions stays hidden, which leaves the page with an amber notice saying "Sie sind angemeldet" and no way to sign out from it (the #signout button is inside the hidden actions). The demo's denied state renders that, skeleton and all. Fix it needs: render the identity and unhide #kh-actions from the /me body before the surfaces check, or catch forbidden after renderIdentity has run.
• 2026-09-12 (measured at c594dfc, schluessel.astro 360 to 361 and 604 to 622, prima-api.ts 634 to 636, 687 to 708, 710 to 744, 268 to 280): a 404 on the keys routes at load does not produce a page with two quiet notices. resolveWorkspace calls resolveTenantId, which is ensureGatewayKey, which mints through POST /api/developer/keys when no record for this sid is in sessionStorage; that 404 is classified unavailable, is thrown outside any card's try, and lands in the gate's error branch with "Dieser Dienst ist noch nicht freigeschaltet." Only with a stored key does the page reach ready, and then the list card alone goes quiet at load (failCard 341 to 348 acts on that card's own call); the create card goes quiet after a submit returns 404 (555). The demo's unavailable state is the composite of those two branches, labelled as such.
• 2026-09-12 (measured at c594dfc, onRevoke 476 to 481 and classify 272): a 404 on DELETE /api/developer/keys/{id} (another workspace's key, a stale row) is classified unavailable and rendered as "Dieser Dienst ist noch nicht freigeschaltet." in the list card's error branch, which is the wrong sentence for "this key is not yours or no longer exists". The list is not reloaded on that path (475 runs only after a successful revoke), so the stale row stays until "Erneut versuchen". Fix it needs: a 404 on DELETE mapped to its own code and a reload after it.
• 2026-09-12 (measured at c594dfc, billing.ts 810 to 814): an account with no workspace reaches the gate's error branch with the money page's sentence ("... kein Guthaben, das aufgeladen werden könnte"), because the seam's tokens are shared across the signed-in pages. True, but odd on a page about keys. Copy, not behaviour.
• 2026-09-12 (measured at c594dfc, schluessel.astro 551 to 554, and at fd8558f, developer_router.py 113 to 126): the 403 branch under the name field exists for the server's scope refusal, and this page always sends ["ai"], so at c594dfc it can fire only for a membership or surface refusal. The demo's create-refused state shows the scope sentence because it is the one the branch was written for.
• 2026-09-12 (measured at c594dfc, gateway-key.ts 125 to 129, and at fd8558f, developer_router.py 135 to 136 and 201): the POST's expires_at is a naive utcnow() ISO string with no offset, which Date.parse reads as local time; the list's expires_at is the column value with its offset. The page's list reads the list response only, so "läuft ab" is right; the client keeps its own mintedAt for the portal key's expiry for the same reason.
• 2026-09-12 (measured at fd8558f, developer_router.py 240 to 253): the list response omits scopes, so this page cannot show a key's scope and does not try; the "genau den Scope ai" sentence in the create card is the rule, not a read.
• 2026-09-12 (rendering trap): the shell's branches are all in the HTML, hidden by [data-when]; a screenshot of the served page before the script runs shows the loading skeleton and nothing else, and the verifier's session: anon capture shows the navigation to /anmelden/ begun. The demo renders each branch as its own state; verify.route matches loading at best.
• 2026-09-12 (rendering trap, demo-frame.css at 86fe9d1): p, h1, h2 and code inside a frame inherit the frame's reset, so the demo uses div, h3 and span.mono; and the skeleton's @keyframes shimmer is left out because the capture rules pause animations anyway.
• 2026-09-12 (rendering trap, host side, prima.li/src/index-site/demo-frame.css at 86fe9d1, lines 79 and 81): .demo-frame .demo-stage--viewport { padding: 0; overflow: hidden } is written before .demo-frame .demo-stage { padding: var(--space-lg); overflow-x: auto } at the same specificity, so the generic rule wins and a viewport stage keeps its 24 px padding and its sideways scroll. DemoFrame.astro's fit() (lines 44 to 50) zooms the 1440 px box to stage.clientWidth, the box then sits behind the 24 px left padding, its right 24 px overflow the stage, and the frame scrolls 48 px sideways; the right edge of every frame of this demo is clipped on the docs page until scrolled. Not a defect of the demo; it affects every recipe that declares viewport:. Fix it needs (prima.li): move line 79 below the generic rule or raise it to .demo-frame .demo-stage.demo-stage--viewport.
• 2026-09-12 (@prima-modules/prima-tokens at its 03f4205 pin): no state colours in tokens.css, so the demo declares the notice palette, the chip green and the refusal red locally (--dpk-*).
• 2026-09-11 (measured then, prima-api.ts 99 to 103): an ai-scoped key answers 403 on /api/auth/me and /api/developer/keys (the prefix lock); key management therefore runs on the session, and "a key that could mint more keys would be a privilege-escalation primitive".
• 2026-08-04 (developer_router.py 267 to 278 at fd8558f, dated in its comment): GET and DELETE filter to the workspace only when X-Workspace-ID is present; this page always sends it, so a key of the same user in another workspace is not listed here.

Reference implementation

Branch: prima-developer w6-konto at c594dfc (2026-09-12), one commit past the d5f9aa8 the inventory row names (the desktop hand-over; schluessel.astro is unchanged between the two). Paths relative to the repo root:

• src/pages/schluessel.astro (632 lines): guard and invariant comments 7 to 21, band 30 to 51, gate branches 65 to 116, sub-navigation 118, create card 121 to 207 (form 134 to 163, reveal 166 to 187), list card 210 to 262, housekeeping card 265 to 307, script 314 to 632 (failCard 341 to 348, resolveWorkspace 360 to 379, keyRow 382 to 439, loadKeys 441 to 458, onRevoke 461 to 482, showReveal and hideReveal 485 to 505, wireCreate 507 to 588, renderIdentity 591 to 602, boot 604 to 622).
• src/lib/prima-api.ts (1442 lines): header (invariants A, B, C, the backend contract, the error envelope, the two credentials) 1 to 139, ApiError and classify 214 to 280, errorMessage 282 to 322, request, keyRequest, send 335 to 443, Account and requireSession 464 to 546, signOut 557 to 578, displayName 580 to 583, workspaces 590 to 636, ensureGatewayKey and mintGatewayKey 687 to 744, revocation and housekeeping 756 to 908, ApiKeySummary, listKeys, isSessionKey, createKey, revokeKey 914 to 958, formatDate 1428 to 1432.
• src/lib/gateway-key.ts: GATEWAY_KEY_TTL_DAYS 99, gatewayKeyMintBody 110 to 122, chooseTenant 204 to 208, GatewayKeyRecord 218 to 230, acceptMintedKey 251 onward.
• src/lib/auth.ts (951 lines): session storage 548 to 659, the per-session key storage 662 to 866.
• src/components/AppNav.astro (26 lines): the five links, aria-current by current.
• src/styles/app.css (867 lines): band 7 to 44, cards 68 to 103, state machine 105 to 122, skeletons 123 to 150, notices 152 to 199, empty 201 to 219, rows 293 to 326, chips 384 to 394, sub-navigation 560 to 574, reveal 608 to 659, fields 661 to 715, row actions 717 to 733, copy button 823 to 834.
• src/layouts/Layout.astro (207 lines): header 51 to 77, nav styles 135 to 175.

Deviations of the reference from this recipe, dated 2026-09-12: the create card's dead end after a keyless 200; the denied account's permanent skeleton and hidden sign-out; the 404-on-revoke sentence; the money sentence for no_workspace on a keys page; no test of the page script; the inventory row's stale tenant description.

Acceptance checks

From prima-developer at c594dfc, or a new portal built to this recipe:

1. grep -n 'scopes: \["ai"\]' src/lib/prima-api.ts prints line 953 as its only match outside a comment (at c594dfc the other four matches, lines 128, 676, 939 and 1024, are *-prefixed comment lines) and grep -n 'GATEWAY_KEY_SCOPES' src/lib/gateway-key.ts prints its declaration and the spread in gatewayKeyMintBody; no other scopes: [ literal exists in src/ outside comments and *.test.ts (the scopes: string[] at gateway-key.ts 113 is the type of the mint body, not a value).
2. grep -c 'innerHTML' src/pages/schluessel.astro prints 0.
3. npx astro build with a configured base, then grep -o '[A-Za-z0-9._-]*@[A-Za-z0-9.-]*' dist/schluessel/index.html | sort -u prints the support mailbox and nothing else (no account address in the shell), grep -c 'prima_pk_' dist/schluessel/index.html prints 0, and grep -c 'data-when=' src/pages/schluessel.astro prints 13.
4. npm test prints # pass 173 (or the new app's count) and # fail 0.
5. Browser walk-through against dist/ served statically (tooling/verify/astro-static.sh <site> /schluessel --serve) with the API mocked: (a) no session: open /schluessel/, observe the address bar at /anmelden/; (b) with a session and /me answering surfaces: ["prima_web"]: observe the amber "nicht freigeschaltet" notice, the band skeleton still in place (#whoami unchanged, #kh-actions still hidden, so no "Abmelden"), no sub-navigation, and no redirect; (c) /me ok, one workspace, /keys []: observe "Noch kein Schlüssel" and "Workspace: " under the form; (d) type a name, submit, mock 200 with api_key in key: observe "Einmalig", the key in exactly one element (document.body.innerText.split(key).length === 2), sessionStorage without it, the list re-fetched; click "Ich habe ihn gesichert", observe the panel gone and #reveal-key empty; (e) click "Sperren" on an active row, cancel the confirm, observe no request; accept it, mock 200, observe two GET /keys in the log and the row's chip "Gesperrt" after the reload; (f) with prima.dev.gateway-key.v1 seeded in sessionStorage for the session's sid (or POST /keys mocked 200 for the mint) and then GET /keys mocked 404: observe the list card's quiet notice at load; type a name and submit with POST /keys mocked 404: observe the create card's quiet notice and no red border on either card; without the stored record a 404 on the mint lands in the gate's error branch reading "Dieser Dienst ist noch nicht freigeschaltet." and no card is shown; (g) /keys mocked 503: observe "Schlüssel konnten nicht geladen werden." and "Erneut versuchen" re-fetching.
6. Demo gate: npm run check prints no line for this recipe; in the prima.li checkout, PRIMA_MODULES_DIR=<this repo> npm run build:index writes dist/docs/modules/identity-auth/ui/developer-portal-keys-page/index.html, and opened in Playwright the page has ten figure[data-demo-state] elements each with a .dpk child inside a .demo-viewport of width 1440 and pageerror count 0 (verified 2026-09-12 against prima.li at 86fe9d1).
7. Verifier: node tooling/verify/compare.mjs identity-auth/ui/developer-portal-keys-page --state loading --docs http://127.0.0.1:4321 --app http://127.0.0.1:4320 --app-repo <prima-developer> with the portal served by astro-static.sh; the session: anon capture must be taken before the guard navigates (--settle 0), the report's page_errors is empty on both sides and mismatch_ratio is read for the band and the skeleton card only, excluding by name the footer (not in the demo), the font and the purple (RENDERING.md section 7); the threshold is mismatch_ratio below 0.02 over that region (set 2026-09-12, not yet measured: the docs capture is the .demo-stage element, compare.mjs 198 to 203, so until prima.li fixes the stage padding, Gotchas, the demo side carries a 24 px inset the app side does not, and a run before that fix is read for the two named parts only, not for the frame's edges). A ready comparison needs a signed-in session against a mocked API and is not a harness feature at 86fe9d1.