Skip to content

administration.md

Latest commit

 

History

History
247 lines (173 loc) · 6.18 KB

administration.md

File metadata and controls

247 lines (173 loc) · 6.18 KB
Raw

Administration

English | 简体中文

The proxy provides two administration surfaces:

  • A loopback-only local route used by the bundled admin CLI.
  • An optional remote management API protected by admin-api-key.

Both surfaces call the same user, usage, and Codex auth management handlers. Management responses use Cache-Control: no-store.

Local Admin CLI

The CLI connects to http://127.0.0.1:8317 by default:

codex-oauth-proxy admin users list

It calls /v0/local-admin/*. The server accepts this route only when the request's remote address is loopback (127.0.0.1 or ::1). It does not require or send admin-api-key.

Use --url for another port or path on the same local service:

codex-oauth-proxy admin users list \
  --url http://127.0.0.1:8318

Use --json with any admin command for machine-readable output:

codex-oauth-proxy admin users list --json

Global admin flags may appear after the leaf command.

User Commands

List Users

codex-oauth-proxy admin users list
codex-oauth-proxy admin users list --enabled true
codex-oauth-proxy admin users list --enabled false

Create a User

codex-oauth-proxy admin users create alice

User names are required and unique without regard to case. A new user is enabled by default and receives one active generated API key.

The create output includes the plaintext key once.

Get a User

codex-oauth-proxy admin users get usr_xxx

Rename a User

codex-oauth-proxy admin users update usr_xxx --name alice2

Enable or Disable a User

codex-oauth-proxy admin users enable usr_xxx
codex-oauth-proxy admin users disable usr_xxx

A disabled user cannot authenticate proxy or user API requests. The stored API key remains present and works again if the user is re-enabled.

Reset an API Key

codex-oauth-proxy admin users reset-key usr_xxx

Resetting a key:

  • Disables every previously active key for the user.
  • Creates one new active key.
  • Returns the new plaintext key once.
  • Does not delete historical usage attributed to older key IDs.

Usage Commands

Rolling Snapshot

codex-oauth-proxy admin usage snapshot
codex-oauth-proxy admin usage snapshot --user-id usr_xxx
codex-oauth-proxy admin usage snapshot --api-key-id key_xxx

Human-readable output shows request and token totals for the rolling 5-hour and 7-day windows.

Timeseries

codex-oauth-proxy admin usage timeseries \
  --window 7d \
  --step 1h \
  --group-by user

Available flags:

Flag Values
--window 5h, 24h, 7d, 30d, today
--step auto, 10m, 30m, 1h, 6h, 1d
--group-by Comma-separated user, api_key, model, reasoning_effort, service_tier
--fill none or zero
--user-id One user ID
--api-key-id One API key ID

The default window is 7d; the default grouping is user. Automatic step size depends on the selected window.

Docker Administration

The local route sees the host-side CLI connection as non-loopback when the server runs in a container. Run the CLI inside the proxy container:

docker exec codex-oauth-proxy \
  /codex-oauth-proxy/codex-oauth-proxy admin users list

For scripts or Grafana outside the container, enable and use the remote management API instead.

Remote Management API

Set a non-empty key:

admin-api-key: "replace-with-a-long-random-secret"

Then authenticate /v0/management/* requests with either:

Authorization: Bearer <admin-api-key>

or:

X-API-Key: <admin-api-key>

When admin-api-key is empty, remote management routes return 404. Local admin routes remain available to loopback clients.

Example:

curl http://127.0.0.1:8317/v0/management/users \
  -H 'Authorization: Bearer admin-change-me'

See API Reference for request and response shapes.

Codex Auth Operations

Codex auth status and recovery actions are exposed through the management APIs. The bundled CLI does not add a separate auth command group.

List safe auth status locally:

curl http://127.0.0.1:8317/v0/local-admin/auths

Force refresh through the remote API:

curl -X POST http://127.0.0.1:8317/v0/management/auths/refresh \
  -H 'Authorization: Bearer admin-change-me' \
  -H 'Content-Type: application/json' \
  -d '{"account_id":"acct_xxx"}'

Enable, disable, and clear a time-based cooldown by replacing the final path with:

/auths/enable
/auths/disable
/auths/cooldown/clear

Enable and disable update every source file for the account. Enable is local validation only; it does not refresh tokens or clear health. Disable affects new selection but does not terminate active HTTP, SSE, or WebSocket traffic and does not delete bindings.

Clear one user's exact session binding:

curl -X POST http://127.0.0.1:8317/v0/management/session-bindings/clear \
  -H 'Authorization: Bearer admin-change-me' \
  -H 'Content-Type: application/json' \
  -d '{"user_id":"usr_xxx","session_key":"raw-session-key"}'

Omit session_key to clear all bindings for that user, or send only account_id to clear bindings targeting one auth. No global clear or administrator-selected target migration is available.

Unidentified auths remain visible in status but are read-only. Management logs include action, safe account/user identity, outcome, and deleted counts. They do not include OAuth tokens, admin keys, raw session keys, source paths, or raw upstream response bodies.

User Self-Service

A managed user API key can access:

  • Current user and key metadata.
  • API key reset.
  • Today's UTC usage.

Resetting through the user API invalidates the credential used for the request and returns a new plaintext key. The caller must switch to the new key.

Key Handling

  • Managed keys use the cop_ prefix.
  • Only the SHA-256 hash is persisted for authentication.
  • List and detail responses include key_prefix and masked_key, not plaintext.
  • Creation and reset are the only operations that return plaintext.
  • One user can have only one enabled API key at a time.
  • A key reset disables the old key immediately.