Files
moloapp/src/openai/admin/SPEC.md
T
retoorandClaude Sonnet 5.5 9e550889cc feat(clients): openai admin: organization admin API, usage, costs, audit logs, webhooks
121-call table checked against the OpenAI OpenAPI document, admin-key-only
client, destructive guards, WebhookVerifier (Standard Webhooks HMAC-SHA256),
demo routes under /ai/openai/admin, local and opt-in live tests.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-24 07:43:17 +02:00

11 KiB

OpenAI organization administration - Specification

Owned directory: src/openai/admin/. Namespace molo::openai::admin. Depends on the src/llm foundation (ApiClient, Service, Config, ApiError) and src/security/crypto (Hmac, Base64, SecureRandom). Plan: plans/17-llm-vendor-platforms.md.

1. Scope

The OpenAI organization administration API (/v1/organization/*), the webhook endpoint management API (/v1/webhook_endpoints*, /v1/webhook_event_types) and webhook delivery verification. 121 calls in one table:

  • Admin API keys, users (and user role assignments), invites, groups (users, role assignments), custom roles.
  • Projects: create, list, get, modify, archive; project users, service accounts (and their API keys), project API keys, rate limits, project groups, data retention, model permissions, hosted tool permissions, spend limit, spend alerts, certificates.
  • Organization: certificates (upload, list, get, modify, delete, activate, deactivate), spend limit, spend alerts, data retention, external storage.
  • Usage (completions, embeddings, moderations, images, audio speeches, audio transcriptions, vector stores, code interpreter sessions, file search calls, web search calls, decisions), costs, audit logs (all filters, 149 event types).
  • Webhooks: event catalog (30 payload shapes, 27 subscribable types), envelope parser, WebhookVerifier, endpoint management (list, get, create, update, delete, rotate secret, test, event types).
  • Data residency: residency / geography on project create and modify, PublicProjectResidency (15 values), regional hosts (Regions).

Not here: Responses, chat and the rest of the inference API (src/openai/core), files, batch, fine-tuning, vector stores, realtime (src/openai/platform). ChatGPT-side admin products (Compliance API, SCIM) have no entry in the OpenAPI document and are not implemented.

2. Module map

File Concern
caps.h Static ceilings (AdminCaps)
calls.h/.cpp The ONE call table (kCalls, 121 rows) and used schema fields (kSchemas); CallTable::render, method, auth, destructive
admin_client.h/.cpp AdminApiClient (admin key only), ProjectApiClient (webhook endpoints, project key only), KeyPolicy, Regions
admin_service.h/.cpp AdminService : llm::Service: execute runs one table row with all guards; walk
validate.h/.cpp Validate: text, id, enum, email, range, count, epoch, https URL, confirmed
query.h/.cpp Query (validated, percent-encoded), ListOptions
page.h/.cpp Page, PageWalker, WalkResult (truncation reported)
requests.h/.cpp Typed bodies: InviteRequest, ProjectCreate, ProjectUpdate, ProjectUserCreate, UserUpdate, ServiceAccountCreate/Update/KeyCreate, ProjectApiKeyUpdate, RateLimitUpdate, CertificateUpload, SpendAlertSpec, SpendLimitSpec, RoleSpec/Update, ModelPermissions, HostedToolPermissions, DataRetention, ExternalStorageSpec, WebhookEndpointSpec
identity.h/.cpp AdminApiKeys, Users, Invites, Groups, Roles
projects.h/.cpp Projects, ProjectUsers, ServiceAccounts, ProjectApiKeys, RateLimits, ProjectGroups, ProjectPolicies
governance.h/.cpp Certificates (org or project scope), SpendAlerts (org or project scope), OrganizationPolicies, ExternalStorage
usage.h/.cpp UsageQuery, CostQuery, Usage, Costs, UsageSummary
audit_log.h/.cpp, audit_events.h/.cpp AuditQuery, AuditLogs, AuditEventCatalog
webhook_events.h/.cpp WebhookEvents (catalog), WebhookEvent, WebhookEnvelope
webhooks.h/.cpp WebhookVerifier, WebhookHeaders, WebhookCounters, WebhookEndpoints
call_runner.h/.cpp CallRunner: any table row by key (used by the example's generic routes)
openai_admin.h/.cpp OpenaiAdmin facade (all services on one client)
crypto_link.cpp Link shim, see Gaps
tools/check_spec.py Fails when the table, schemas, catalogs or coverage differ from the OpenAPI document
tools/probe_paths.py Unauthenticated probe of every GET row

3. Static caps

Knob Value
list page size 1..100 (api), default 20
page walk 20 pages, 2000 items, then truncated with reason and resume cursor
usage buckets 1d: 31, 1h: 168, 1m: 1440 (api); costs 1..180 (api)
filter arrays 100 values of 256 chars; group_by 8; audit event_types 50
cursor / token 512 chars
names / email / description 256 / 320 / 1024 chars
permissions per role / models per list / scopes / invite projects 256 / 500 / 32 / 100
key expiry 1..31536000 s (api maximum)
certificate PEM 64 KiB, no private key material accepted
certificate ids per toggle 10
request body 256 KiB
webhook body 1 MiB; signature header 4096 chars, 8 signatures
webhook tolerance default 300 s, 0..3600
webhook secret decoded whsec_ key at least 24 bytes
time values unix seconds 1..4102444800

Local choices, not API values: walk ceilings, filter and text limits, spend alert recipients (1..10), rate limit values (0..1e12), the 3600 s tolerance ceiling.

4. Contracts

  • Every URL comes from kCalls; ids go through Service::valid_id; query names must be rows of the call (effective_at[gt] style object keys allowed for effective_at); body fields must be in the row, required ones present.
  • Input is validated before any traffic: ApiError 400 INVALID_ARGUMENT. No credential: NotConfiguredError 503.
  • Credentials. AdminApiClient reads OPENAI_ADMIN_KEY and refuses any key not starting sk-admin- with 401 WRONG_KEY_KIND (message never echoes the key). So a regular or project key can never reach /organization/*. The OpenAPI document secures /webhook_endpoints* and /webhook_event_types with the regular ApiKeyAuth ("endpoints of the authenticated project"), so WebhookEndpoints takes a ProjectApiClient (OPENAI_API_KEY, admin keys refused). A service built for one kind refuses rows of the other.
  • Destructive rows (every DELETE plus projects.archive, certificates.deactivate, projects.certificates.deactivate, data_retention.update, projects.data_retention.update, webhook_endpoints.rotate_secret) throw unless confirm=true; the typed methods take confirm without a default. Example routes /destroy are dry runs unless the body has "confirm":true.
  • Secrets returned once (admin key create, service account and its key create, webhook endpoint create and rotate) are in the answer only; nothing is logged.
  • Lists report truncation (WalkResult::truncated), never silently.
  • Webhook verification: see webhooks.h. Per Standard Webhooks as implemented by openai-go: signed string id.timestamp.body, key from whsec_<base64> (canonical base64, >= 24 bytes) or raw bytes, v1,<base64> entries, any match accepted, constant-time compare (SecureRandom::constant_time_equal), tolerance both directions. Stricter than openai-go: bare (unprefixed) and non-v1 entries are ignored. Rejections are counted per reason (WebhookCounters, shown at /status). unwrap parses only after verifying.
  • Region hosts <code>.api.openai.com for us eu au ca jp in sg kr gb ae.

5. Example routes (/ai/openai/admin)

GET / (page), /status, /calls, /audit-events, /webhook-events. POST /read (any GET row), /write (mutating, not destructive), /destroy (destructive, dry run unless confirm), /usage, /costs, /audit (typed queries, optional walk), /webhook/verify (local, no credential). Order: 422 on bad input, then 503 not_configured; oversize body 413.

Sources

  • OpenAI OpenAPI document, openai/openai-openapi openapi.json at commit 8243cc8fa6f04430fb1f1a6a2cb926fbeb4f7f26 (2026-10-24, info.version 2.3.0, the manual_spec branch is older and lacks groups, roles, spend, retention). Paths, operation ids, security, parameters, bodies, schemas, the webhooks map, AuditLogEventType, PublicProjectResidency, ProjectEventTypeEnum.
  • Official openai-go SDK (main, .castiron.stats.yml carries no spec URL any more): api.md and webhooks/api.md (method + path of every row), webhooks/webhook_helpers.go and webhook_secret.go (verification algorithm), adminorganizationauditlog.go (bracket array/nested query format), adminorganizationusage.go. Python SDK tests (tests/api_resources/test_webhooks.py) confirm client.webhooks.* endpoint management.
  • Standard Webhooks specification (standard-webhooks/standard-webhooks spec/standard-webhooks.md): headers, v1, signature format, whsec_.
  • Unauthenticated probes of *.api.openai.com (below).

Verified against spec

python3 -I src/openai/admin/tools/check_spec.py, run 2026-10-24: spec ok: 121 calls, 91 schemas, 121 in-scope spec operations covered, 149 audit event types, 30 sent webhook event types, openai-go lists all 121 rows. It checks per row: method, path, operationId, security scheme, path and query parameters (both directions), request schema name, body fields (both directions), required fields, 200 response schema; every schema field read; audit and webhook catalogs; usage group_by enums; webhook data fields; and that no in-scope spec operation is unwrapped. --head checks the newest main.

Verified live

2026-10-24, no key, invalid key sk-admin-invalid:

  • python3 -I src/openai/admin/tools/probe_paths.py: all 58 GET paths of the table answer 401, /v1/organization/nonexistent_probe_path answers 404.
  • Error shape: 401 {"error":{"message":"Incorrect API key provided: ...", "type":"invalid_request_error","param":null,"code":"invalid_api_key"}} (ApiError::type() is invalid_request_error).
  • Hosts api, us, eu, au, ca, jp, in, sg, kr, gb, ae .api.openai.com resolve and answer 401 on /v1/organization/users.
  • Opt-in test openai_admin.live_read_only (MOLO_LIVE_NET=1): invalid-key probe passes; the read-only list calls (projects, users, limit 1) need OPENAI_ADMIN_KEY and have not run (no key).

Unverified

Everything that needs an admin key: the real shape of every response (typed accessors read only the list envelope and usage/cost result numbers), whether the server accepts repeated name= for usage arrays (spec form; the SDKs send name[]), effective_at[gte] nesting (SDK form), that an admin key always starts sk-admin- (docs examples; the check is a prefix test), the 400 and 404 bodies of mutating calls, include=content for certificates, key expiry maximum applying to admin keys (spec says so), external storage provider field sets (from the spec's oneOf), video.* webhook payloads (selectable event types without a payload schema), live.transport.incoming data fields (spec lists a type inside data), spend amounts being cents (spec text for the limit; assumed for alerts). The Standard Webhooks vector's signature was recomputed with python3 hmac, not taken from OpenAI. Webhook delivery retry behaviour is OpenAI's and untested.

Gaps

  • src/ai.mk compiles only Base64.cpp from src/security/crypto; until the integration adds Sha256.cpp, Hmac.cpp, SecureRandom.cpp to AI_SRCS, crypto_link.cpp includes them. Delete crypto_link.cpp then (duplicate symbols otherwise).
  • Typed response structs are not generated; responses are Json.
  • No SCIM, Compliance API or ChatGPT workspace admin (no OpenAPI entries).
  • Resume of a truncated walk restarts at the page that hit the ceiling.