API keys

The API keys page is the operator surface for runtime client credentials. A Pool API key lets a client send requests through one Pool. It does not represent an upstream account, and it is not an operator login credential.

Use this page when you need to answer:

1. which client credentials exist for each Pool
2. whether a key is active, paused, or revoked
3. which model policy applies to a key
4. whether request or token limits are configured
5. when a key was last used or expires
6. when a key needs rotation, pause, revoke, or deletion

The page is a lifecycle and policy registry, not an analytics page. It shows display names, safe key prefixes, Pool grouping and filtering, status, dashboard-access state, last-used and expiry state, model-policy summaries and warnings, operator notes, and action menus. It does not show usage totals or charts, and it does not show raw Pool API keys after the one-time secret dialog is closed.

Use the API Key Observatory for read-only analytics scoped to one API key. Use the admin Stats page for Pool-level aggregate request, token, and cost analytics, and Request logs for request-level investigation, including API key context, outcomes, and available settled usage metadata.

What an API Key Controls

A Pool API key is the bearer credential a runtime client uses for Codex Pooler routes. The key authorizes the client into one Pool. The Pool then decides which eligible upstream account receives the request.

An API key controls:

1. the owning Pool
2. display name and operator notes
3. lifecycle status, such as active or paused
4. optional expiry
5. allowed model policy
6. optional enforced request fields
7. default request and token limits
8. one optional model-scoped limit override

API key policy does not bypass Pool routing. The Pool still needs active upstream assignments, compatible models, fresh credentials, and usable quota evidence.

Pool Registries

Keys are grouped by Pool. Each Pool registry has a compact identity rail and a list of credential records that adapts from stacked mobile details to a dense desktop grid.

Record area	Meaning
Credential	Operator display name and safe key prefix. The prefix helps identify a credential without exposing the full bearer token.
Status	Lifecycle state for the client credential. Active keys can authenticate new runtime requests; paused or revoked keys should not.
Lifecycle	Last-used and expiry state. These help identify credentials that need review or retirement, without presenting traffic totals.
Policy	Short model-policy summary, such as all models or selected models. A warning identifies configured models that are not currently available to the Pool.
Actions	Dotted menu for edit, pause, resume, rotate, revoke, and delete actions.

Operator notes appear behind the small information icon when present. Keep notes operational and sanitized; do not store secrets, customer content, or raw keys in notes.

Create API Key

Click Create API key to open the policy wizard.

The wizard has five sections:

1. Basics
2. Models
3. Enforcement
4. Limits
5. Review

The dialog footer keeps Docs on the left and actions on the right. Cancel closes without creating a credential. Create API key submits the policy and then shows the raw key once.

Basics

Basics defines the operator label, owning Pool, status, optional expiry, and operator notes.

Use one key per client, environment, or automation boundary. Separate keys make rotation and request investigation easier because Request logs retain the key context for each recorded request.

Status choices are:

Status	Meaning
Active	The key can authenticate new runtime requests for its Pool.
Paused	The key remains configured but should not admit new runtime requests.

Expiry is optional. Use it for temporary automation or time-bounded access. Leave it blank for long-lived client credentials that are rotated operationally.

Dashboard access

Dashboard access is a separate, disabled-by-default capability on the API key. Enable it in the Basics step when the key holder should be able to open the read-only API Key Observatory. The same policy wizard manages this setting; there is no separate dashboard settings page.

This capability does not replace runtime API-key permission. Runtime requests still use the key’s active status, Pool, model policy, limits, expiry, and the Pool’s routing eligibility. It also does not grant an instance-owner or instance-admin browser session, access to /admin/*, or visibility into other keys.

Owners can manage the setting for their visible Pools. Instance admins need the existing pool_api_key.manage capability for the assigned Pool. The wizard shows the normalized value as Dashboard access: Enabled or Dashboard access: Disabled, and each key card shows a matching badge. The API-key page remains a lifecycle/policy registry: it does not grow usage totals or charts when dashboard access is enabled.

Open the API Key Observatory

The Observatory has its own browser boundary. It is not part of the instance-admin login flow:

1. Open GET /observatory/login.
2. Enter the Pool API key in the password-style Access key field and submit the CSRF-protected form to POST /observatory/login. The credential is accepted only in that form; never add it to a URL or query string.
3. A valid active, non-expired key with Dashboard access enabled receives a separate HttpOnly, SameSite Lax browser session and redirects to GET /observatory.
4. The Observatory page can be ended with DELETE /observatory/logout from its Log out control. Logout removes the dashboard session and clears the browser cookie.

The dashboard session lasts at most 14 days, does not renew its expiry while idle or active, and is limited to 10 concurrent sessions per key. The database stores only a hash of the browser session token. The raw Pool API key is not persisted as dashboard session data, rendered in the dashboard, or included in logs. Login attempts that fail because a key is missing, malformed, paused, revoked, expired, not enabled for Dashboard access, or attached to an inactive Pool use the same generic failure message.

Observatory contents and privacy

The authenticated dashboard is read-only and scoped to the one API key used to sign in. It offers 1h, 5h, 24h, and 7d windows with:

• success, cache, cost, throughput, and latency summaries
• a model distribution based on settled token totals
• Traffic buckets with fresh and cached token values, plus interval and cumulative views
• at most 12 recent outcomes showing time, model, sanitized endpoint class, status, latency, tokens, and cost

Cost values are reporting estimates or settled accounting values, not provider invoices. Partial accounting, missing pricing, no activity, paused refresh, disconnection, and temporary read errors are shown as explicit states rather than invented totals.

Dashboard data is metadata-only. It excludes prompts, completions, file or media contents, request and response bodies, headers, cookies, bearer credentials, raw idempotency keys, IP addresses, user agents, upstream identities, Pool controls, other API keys, and raw error text.

Models

The Models step chooses model scope and optional enforced request fields.

Model modes are:

Mode	Meaning
All models	Allows current and future routable models for the Pool, subject to upstream eligibility.
Selected	Allows only checked catalog models and any manual model identifiers saved on the key.
Deny all	Keeps the key valid but blocks model use. Use this for staged credentials or emergency containment.

Catalog models are derived from current routable model metadata. Manual model identifiers support controlled exceptions when a model is not yet present in the catalog.

Enforced request fields let the key override selected client request values:

1. enforced model
2. reasoning policy
3. enforced service tier

The reasoning policy offers three modes:

1. Unrestricted leaves omission absent and preserves any effort the route already accepts. This is the default for keys with neither reasoning value configured.
2. Allow up to permits only known efforts through the selected ceiling: none, minimal, low, medium, high, xhigh, max, or ultra. The selected model’s available known levels can narrow the result further. An omitted request uses the permitted model default, or the highest permitted known level.
3. Always use applies one exact effort to every request. Existing keys that already have an enforced reasoning effort stay in this mode.

Allow up to rejects rather than changes a disallowed request. An effort above the ceiling, an unknown or custom effort, or an omission with no permitted level returns 400 reasoning_effort_not_allowed before upstream work. Backend Responses and public Responses identify reasoning.effort; Chat Completions identifies reasoning_effort.

none is an explicit configured value. Leaving the policy Unrestricted is different because it leaves client control intact. minimal and ultra are evaluated as their own client-facing values, then backend dispatch rewrites them to low and max respectively when required by the upstream target. Safe policy and reasoning summaries can distinguish the requested, applied, and effective values.

Limits

The Limits step saves optional policy caps.

Default limits can cap:

1. requests per minute
2. tokens per day
3. tokens per week
4. input tokens per request
5. output tokens per request

Leave a field blank when no cap should be saved. A blank limit is different from a zero limit.

The model-scoped override is an optional single-model override. Use it when one model should be more constrained than the default policy. Additional model rows are not part of the current wizard.

Review

The Review step shows the normalized effective policy before saving, including the selected Pool name, lifecycle settings, model access, enforced values, and configured limits.

Resolve review errors before saving. The submit button stays disabled when required policy data is missing. The review summary is useful because it shows what the key will actually enforce after normalization, not only what the operator entered on the previous steps.

Review does not show request, token, or cost totals. Open the Observatory for one-key analytics, Stats for Pool-level aggregates, or filter Request logs when you need to investigate recorded traffic.

One-Time Secret Dialog

After a key is created or rotated, Codex Pooler shows the raw bearer token exactly once. Copy it before closing the dialog.

Future views only show the safe prefix. If the raw value is lost, rotate the key and update the client with the new value. Do not store raw keys in operator notes, screenshots, tickets, chat, request logs, audit comments, or public docs.

The Observatory login accepts the raw key only for the form exchange. It creates a separate browser session and does not make the raw value available again. Treat the key as a one-time secret at creation or rotation and keep it in the client or password manager that owns the runtime integration.

Action Menu

Open the dotted menu on a key row for lifecycle actions.

The current actions are:

Action	What it does
Edit	Opens the same policy wizard for an existing key. Stored secret material is not shown.
Pause	Disables new runtime authentication for an active key while keeping the key configured.
Resume	Returns a paused key to active authentication.
Rotate	Creates a new raw bearer token for the same key record and shows it once. Update clients immediately. The key keeps its identity, audit trail, and Request log attribution.
Revoke	Marks the key revoked. Revoked keys cannot be edited or resumed.
Delete	Opens a confirmation dialog that requires the key prefix. Delete permanently removes the key and related request history from this instance.

Prefer pause for temporary containment, rotate for suspected exposure, revoke for permanent credential retirement, and delete only when the key and its related local history should be removed.

Operational Checklist

When client traffic is rejected or not behaving as expected, check API keys in this order:

1. confirm the client is using a Pool API key, not an upstream account credential
2. confirm the key belongs to the expected Pool
3. confirm the key status is active
4. confirm the key is not expired
5. confirm model policy allows the requested model
6. confirm enforced request fields are expected
7. confirm request and token limits are not exceeded
8. check the owning Pool for active upstream assignments
9. use Request logs filtered by Pool or key metadata to inspect recent failures
10. use Audit logs to confirm recent create, rotate, pause, revoke, or edit actions

If the raw key was copied incorrectly or lost, do not create another unrelated key unless the client identity should change. Rotate the existing key so its identity, audit history, and Request log attribution stay attached to the same operator label. Rotation keeps the key record but invalidates every existing Observatory session, so the new raw key must be used for both runtime requests and the next dashboard login. Use the Observatory for per-key analytics and Stats for Pool-level aggregates.

Dashboard session and lifecycle effects

Dashboard sessions are tied to the canonical API key and its current Pool. The following changes invalidate existing dashboard sessions and require a new login when access is eligible again:

Change	Result
Pause	Runtime admission stops and existing Observatory sessions are removed. Resuming the key does not restore a deleted browser session.
Revoke	Runtime and Observatory access stop; the revoked key cannot be resumed or rotated.
Rotate	The key record and history remain, a new raw key is shown once, and all Observatory sessions are removed.
Delete	The key and its dashboard sessions are removed.
Expiry	New login and subsequent session checks fail after the expiry time.
Pool disabled or archived	Dashboard sessions for keys in that Pool are removed and the Pool must be active before login can succeed again.
Key moved to another Pool	Existing sessions are removed; sign in again after the destination Pool and key are eligible.
Dashboard access disabled	Existing sessions are removed without changing the key’s runtime policy.

An open dashboard normally receives the invalidation promptly across application nodes. It also rechecks the database on reconnect, refresh, and the bounded revalidation interval, so a missed relay fails closed rather than leaving stale access active.

Observatory troubleshooting

• The login form says The API key is invalid or unavailable. Ask the key manager to confirm the key is active, unexpired, attached to an active Pool, and has Dashboard access enabled. The message is intentionally generic and does not reveal which eligibility check failed.
• The page returns to login after a lifecycle change. This is expected after pause, revoke, rotate, delete, expiry, Pool disable/archive, Pool reassignment, or Dashboard access disable. Sign in again only after the key is eligible.
• The page says No usage in this window. The key has no recorded activity in the selected window. Try another window or confirm that the client is using this key.
• The page says usage is estimated or unavailable. Accounting or pricing is still settling, missing, or temporarily unavailable. The dashboard does not invent a settled value.
• The page says updates are paused or disconnected. Resume refresh or wait for the browser connection to recover. Hidden tabs and paused views stop periodic refreshes; the last known values remain visible until a new refresh is applied.