Files
moloapp/src/openai/admin/SPEC.md
T

194 lines
11 KiB
Markdown
Raw Normal View History

# 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.