Oceans LLM

Appearance

Admin Control Plane ​

See also: Identity and Access, Configuration Reference, Service Accounts, Budgets, Observability and Request Logs, Request Logs, MCP Invocations, MCP Registry and Discovery, Agent Harness Usage, Agent Session Analysis, Admin API Contract Workflow, End-to-End Contract Tests, OIDC and SSO

This page describes what platform admins can do and which self-service views regular users can open in the browser UI today.

Same-Origin Control Plane ​

The control plane is served through the gateway at /admin.

Normal runtime model:

  • the gateway handles auth, admin APIs, and reverse proxying
  • the SSR app calls back into the gateway through the same-origin client boundary

For the generated contract and artifact workflow, use admin-api-contract-workflow.md.

Live Gateway-Backed Surfaces ​

These areas are backed by real gateway APIs today:

  • sign-in, session lookup, current-session logout, and password rotation
  • API key inventory, creation, and revocation
  • identity users and lifecycle management
  • identity teams and member transfer or removal workflows
  • team-owned service-account management
  • password invite and optional SSO sign-in links
  • OIDC and OAuth pre-provisioning flows
  • spend usage reporting
  • spend budget management for users, service accounts, and user model scopes
  • request-log list and detail inspection
  • MCP invocation list and detail inspection
  • MCP server registry UI, recommended-server catalog, registry CRUD, soft-disable, tool list, and discovery refresh
  • generated client configuration snippets for supported model harnesses; see Client Harness Configuration
  • runtime-gated agent session list and diagnostic inspection; see Agent Session Analysis

Live But Still Maturing Surfaces ​

These pages now read from gateway APIs, but still have capability-detail follow-up work:

  • Models

That split matters for admin expectations and test scope.

The Models page also shows model-level allowlists read-only when present. Unrestricted by model allowlist means no model-level policy is stored for that gateway model. Listed users and teams are normalized refs from config; admins cannot edit this policy from the UI in v1.

Admin-Visible Maturity Cues ​

The current product contract is mixed on purpose:

  • identity, service accounts, spend, API keys, request logs, leaderboard, and Models are live gateway-backed surfaces
  • Models still needs richer runtime capability visibility, including Responses and embeddings support

Tracked follow-up:

API-Key Workflows Available Today ​

Admins can:

  • list API keys with owner summary, grant mode, and grant list
  • create a new key for an explicit user or service-account owner
  • grant access to all gateway models for user-owned keys
  • grant access to an explicit set of gateway models for user-owned or service-account-owned keys
  • copy the raw key once from the create response
  • replace model grant mode and explicit grants for an active key
  • revoke a key so runtime auth rejects it immediately

For service workloads, create a service account for the workload and then create credentials on that service account:

  • give it a workload-specific name
  • grant only the explicit gateway models the workload needs
  • configure an active service-account budget before using active credentials
  • rotate by creating a replacement key, updating the caller secret, then revoking the old key

Current limits:

  • no rename flow
  • no owner transfer flow
  • no secret recovery flow
  • no restore-from-revoked flow
  • revoked keys are read-only
  • model choice is limited to the live gateway model catalog
  • direct team-owned runtime keys are not supported

Identity Workflows Available Today ​

Admins can:

  • sign in as the bootstrap or existing platform admin
  • rotate the bootstrap password when required
  • create users
  • edit user role and membership fields
  • deactivate, reactivate, and reset onboarding for users
  • create teams
  • add existing users to teams
  • invite new users directly into teams
  • pre-provision OIDC users against enabled providers
  • remove team members
  • transfer team members between teams with an explicit destination role
  • manage team service accounts according to their team scope
  • sign out of the current browser session

Current limits:

  • owner memberships stay blocked from removal or transfer in this slice
  • auth-mode switching is limited to invited users
  • OIDC group or claim-to-role mapping is not part of the current admin contract

Admin Auth and Session Behavior ​

Admins can control signed-in page visibility and API-key actions with the top-level permissions config. The gateway returns the resolved page and action sets in each session. The UI uses pages for navigation and actions for API-key controls. The API also enforces each configured API-key action before ownership and team-scope checks. Team admins inherit user grants, and platform admins inherit both lower groups. See Identity and Access for the group and data-scope policy, and see the permissions config reference for syntax.

The default shared page set includes API Keys, Models, Teams, Users, Usage Costs, Leaderboard, Agent Harnesses, Request Logs, MCP Invocations, and Service Accounts. Leaderboard and Agent Harnesses are global read views. Service Accounts is team-scoped for regular users. Hiding a page does not revoke direct API access. The default action set lets users create, update, and revoke their personal API keys. Team owners and team admins can also manage and reveal service-account keys for their team.

User and team write routes have two backend authorization layers. A centralized HTTP mutation guard requires an active platform_admin session for every POST, PUT, PATCH, or DELETE request under /api/v1/admin/identity/users and /api/v1/admin/identity/teams. Each mutation handler also repeats the platform-admin check before it reads or changes identity state.

Current session behavior is cookie-backed and admin-visible:

  • browser cookie state carries the admin session
  • /api/v1/auth/session is the machine-readable session lookup
  • /api/v1/auth/logout revokes the current cookie-backed session and clears the browser cookie
  • expired or missing session state sends the admin back through the auth flow
  • bootstrap admin and regular admin accounts share the same session mechanics after sign-in
  • regular users use the same session mechanics and are sent to /admin/observability/usage-costs after sign-in

What is still missing:

  • broader session-management UI

Spend and Observability Workflows Available Today ​

Admins can:

  • inspect 7-day and 30-day spend windows
  • filter spend by owner kind
  • manage user, service-account, and user model budgets
  • inspect the 7-day or 31-day usage leaderboard
  • inspect 7-day or 31-day self-reported agent harness usage by request count

Regular users can:

  • inspect their own 7-day and 30-day spend windows
  • export their own FOCUS billing rows
  • inspect their own request-log list and details
  • inspect their own MCP invocation list and details
  • inspect the global 7-day or 31-day usage leaderboard
  • inspect global 7-day or 31-day agent harness usage
  • inspect active service accounts for their own team without credential metadata
  • inspect request-log summaries
  • filter request logs by caller service, component, environment, and one bespoke tag match
  • inspect sanitized request-log payload detail
  • see each request log's public operation through row metadata
  • see per-row payload capture mode, byte limits, stream event limit, policy version, and truncation state
  • see per-row MCP/tool cardinality counts for request logs
  • see normalized harness and bounded raw User-Agent detail for request logs
  • inspect request-linked MCP invocations by request id, server, tool, API key, user, team, status, and time range

Additional platform-admin capabilities:

  • compare leaderboard users with average tool exposure and invocation counts
  • inspect grouped agent sessions, request outcomes, cost and time components, score confidence, data coverage, comparison groups, data limits, and formula versions when the runtime setting permits it
  • manage MCP servers from /admin/mcp/servers
  • inspect MCP discovery status as the current server health signal
  • refresh MCP discovery and see bounded failure feedback
  • inspect discovered MCP tools, active state, stable tool ids, schema versions, and JSON schemas
  • manage MCP toolsets, grants, upstream credential bindings, and effective-access previews from the MCP workspace

Request-log payload policy is read-only in the admin UI. Admins configure it through gateway.yaml; see observability-and-request-logs.md.

Agent session calibration data is disabled by default and requires an explicit gateway runtime setting. Only platform admins can access calibration data, and the system does not show the session score during calibration. Team Owners and Admins need both calibrated-score and team-admin access. Team members cannot access this page.

Current limits:

  • spend reporting still lacks provider breakdown
  • admin mutation audit logs are still tracked separately in issue #99
  • request-log detail missing rows return 404 not_found
  • request-log filtering ergonomics still have follow-up work
  • OAuth browser setup and token refresh for MCP upstream credentials remain future work

Service Callers Today ​

The gateway uses first-class service accounts for non-human team callers.

Management rules:

  • platform admins can manage service accounts across all teams
  • team owners and team admins can manage service accounts for their own team
  • ordinary members and non-members cannot manage service accounts
  • service-account deletion is deactivation

Direct team-owned runtime API keys and system-legacy compatibility are removed. Team automation should use credentials attached to a team-owned service account.

Do not confuse this with provider credential auth such as Vertex auth.mode: service_account. Provider service-account auth lets the gateway call an upstream provider; gateway service accounts let callers authenticate to the gateway. See service-accounts.md.

Current Gaps ​

Relationship to Testing ​

The E2E harness treats only live gateway-backed surfaces as contract flows.

  • live surfaces should gain targeted cross-layer coverage as they harden
  • maturing live pages can appear in smoke coverage before every workflow becomes business-flow coverage

Use e2e-contract-tests.md for the test boundary.