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>
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/geographyon 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 throughService::valid_id; query names must be rows of the call (effective_at[gt]style object keys allowed foreffective_at); body fields must be in the row, required ones present. - Input is validated before any traffic:
ApiError400INVALID_ARGUMENT. No credential:NotConfiguredError503. - Credentials.
AdminApiClientreadsOPENAI_ADMIN_KEYand refuses any key not startingsk-admin-with 401WRONG_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_typeswith the regularApiKeyAuth("endpoints of the authenticated project"), soWebhookEndpointstakes aProjectApiClient(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 unlessconfirm=true; the typed methods takeconfirmwithout a default. Example routes/destroyare 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 stringid.timestamp.body, key fromwhsec_<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-v1entries are ignored. Rejections are counted per reason (WebhookCounters, shown at/status).unwrapparses only after verifying. - Region hosts
<code>.api.openai.comfor 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-openapiopenapi.jsonat commit8243cc8fa6f04430fb1f1a6a2cb926fbeb4f7f26(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, thewebhooksmap,AuditLogEventType,PublicProjectResidency,ProjectEventTypeEnum. - Official openai-go SDK (
main,.castiron.stats.ymlcarries no spec URL any more):api.mdandwebhooks/api.md(method + path of every row),webhooks/webhook_helpers.goandwebhook_secret.go(verification algorithm),adminorganizationauditlog.go(bracket array/nested query format),adminorganizationusage.go. Python SDK tests (tests/api_resources/test_webhooks.py) confirmclient.webhooks.*endpoint management. - Standard Webhooks specification (
standard-webhooks/standard-webhooksspec/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_pathanswers 404.- Error shape: 401
{"error":{"message":"Incorrect API key provided: ...", "type":"invalid_request_error","param":null,"code":"invalid_api_key"}}(ApiError::type()isinvalid_request_error). - Hosts
api,us,eu,au,ca,jp,in,sg,kr,gb,ae.api.openai.comresolve 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) needOPENAI_ADMIN_KEYand 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.mkcompiles onlyBase64.cppfromsrc/security/crypto; until the integration addsSha256.cpp,Hmac.cpp,SecureRandom.cpptoAI_SRCS,crypto_link.cppincludes them. Deletecrypto_link.cppthen (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.