Platform admin

Platform administration is for running EvalBook itself, not for running a customer's project. It is held through Bookbag SSO's per-product role for EvalBook (admin), re-read at every sign-in into User.is_platform_admin. EvalBook has no screen that grants it, and no project role or API key can reach it.

A platform admin has no bypass inside a tenant. In the ordinary app they see exactly what their own organization and project memberships allow. Everything that crosses organizations is under /admin, and only there. Every admin query names an explicit organization; only the platform-admin controllers may leave it out.

The four platform capabilities

The capability → role matrix in the application defines four platform capabilities. No role grants them, and an API key is refused with TOKEN_SCOPE when it tries one.

Capability	Page	API
platform.view_audit_log	Admin → Audit log	platform/api/admin/audit, platform/api/admin/audit/chain
platform.view_jobs	Admin → Jobs & deliveries	platform/api/admin/jobs, …/admin/deliveries, …/admin/inbox
platform.manage_jobs	the retry and cancel actions on that page	…/admin/jobs/retry, …/admin/jobs/cancel, …/admin/deliveries/retry
platform.view_diagnostics	Admin → Readiness	platform/api/readiness

The /admin home shows one card per capability the signed-in person holds. For what the project roles are, see Roles and access.

Audit log

The audit log is append-only and hash-chained per organization. Each row's hash covers the canonical JSON of its core fields plus the previous row's hash, and every write EvalBook makes on someone's behalf is recorded in the same transaction as the write: a change that cannot be audited does not happen.

The admin page lists every organization's events, or one organization's when you enter its SSO organization id. Pages hold 50 events by default (the API accepts 1 to 200) and continue with before_id. Verify walks a chain in sequence order and reports the first row whose link or content no longer matches; with the organization left blank it verifies the platform's own chain. scope=platform narrows the list to platform events.

When a project's retention window for audit_metadata passes, the daily purge deletes the event's detail rows and stamps details_purged_at. The event, its summary and its place in the chain stay, and the chain still verifies because it covers the details' digest, not the details. See Retention, export and deletion.

Jobs and deliveries

The page has three tabs across every organization: Jobs (the queue), Sent (the outbox) and Received (the inbox). Each list carries counts by status.

• Jobs are queued, running, succeeded, failed, cancelled or awaiting_reconcile, with their attempt history. With platform.manage_jobs, Retry puts a failed job, or one awaiting reconciliation, back to queued (anything else answers 409 NOT_RETRYABLE), and Cancel answers cancelled or cancelling (the job stops at its next checkpoint). Both are audited as job.retried and job.cancel_requested.
• Deliveries are pending, delivered or failed. Only a failed delivery can be sent again (409 NOT_FAILED otherwise); the retry is audited as outbox.retried with the message's idempotency key.
• The inbox lists receipts and conflicts: a conflict is an inbound event whose idempotency key was seen before with a different payload digest. It is recorded, never applied a second time.

How the queue, the outbox and the inbox behave is on Readiness and operations.

Readiness

Admin → Readiness runs every check fresh and shows each with its detail: databases, SSO, the encryption key, the peer directory and the queue. The anonymous /ready endpoint says only ready or not.

What organization owners and admins see

Owners and admins of an organization at SSO get the same views for their own tenant, without any platform role:

Page	Capability	API
Organization → Audit log	org.audit.read	platform/api/audit, /audit/event, /audit/chain
Organization → Deliveries & jobs	org.jobs.read	platform/api/jobs, /deliveries, /deliveries/retry, /inbox
Organization → Settings	org.settings	platform/api/settings, /settings/update

Organization settings are the defaults new projects start from: the capture mode (full, redacted or metadata_only), the largest body kept inline, and how many days raw bodies and traces are kept. Existing projects keep their own policies. Saves carry expected_revision, and a stale save answers 409 VERSION_CONFLICT rather than overwriting someone else's change. The organization's name, people, roles and billing are managed at Bookbag SSO; the page links there.

The organization home lists the projects the person can open and the plan read from SSO. On the free plan an organization may have 3 active projects; past that, New project is disabled and the page says to archive one or change the plan at Bookbag. A plan change never deletes anything. See Projects.