# 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_` (canonical base64, >= 24 bytes) or raw bytes, `v1,` 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 `.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.