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>
This commit is contained in:
2026-10-24 07:43:17 +02:00
co-authored by Claude Sonnet 5.5
parent 2e0270c043
commit 9e550889cc
47 changed files with 5533 additions and 3 deletions
+193
View File
@@ -0,0 +1,193 @@
# 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.
+111
View File
@@ -0,0 +1,111 @@
#include "openai/admin/admin_client.h"
#include <algorithm>
#include <cctype>
#include "clients/transports/http_transport.h"
#include "llm/config.h"
#include "llm/error.h"
namespace molo::openai::admin {
namespace {
const char* const kCodes[] = {"", "us", "eu", "au", "ca", "jp", "in", "sg", "kr", "gb", "ae"};
// PublicProjectResidency of the OpenAPI document (checked by tools/check_spec.py).
const std::vector<std::string> kResidency = {
"GLOBAL", "US_STORAGE_PROCESSING", "EU_STORAGE_PROCESSING", "JP_STORAGE",
"JP_STORAGE_PROCESSING", "KR_STORAGE", "CA_STORAGE", "SG_STORAGE", "IN_STORAGE",
"IN_STORAGE_PROCESSING", "AU_STORAGE", "AU_STORAGE_PROCESSING", "GB_STORAGE", "AE_STORAGE",
"AE_STORAGE_PROCESSING"};
llm::ApiClientConfig make_config(const char* key_env, Region region) {
llm::ApiClientConfig c;
c.vendor = "openai";
c.base_url = Regions::base_url(region);
c.key_env = key_env;
c.auth = llm::AuthStyle::kBearer;
return c;
}
} // namespace
const std::vector<Region>& Regions::all() {
static const std::vector<Region> regions = {Region::kGlobal, Region::kUs, Region::kEu,
Region::kAu, Region::kCa, Region::kJp,
Region::kIn, Region::kSg, Region::kKr,
Region::kGb, Region::kAe};
return regions;
}
std::string Regions::code(Region region) { return kCodes[static_cast<int>(region)]; }
std::string Regions::base_url(Region region) {
const std::string c = code(region);
return c.empty() ? "https://api.openai.com/v1" : "https://" + c + ".api.openai.com/v1";
}
std::optional<Region> Regions::parse(const std::string& code_text) {
std::string c = code_text;
std::transform(c.begin(), c.end(), c.begin(), [](unsigned char ch) { return std::tolower(ch); });
if (c.empty() || c == "global") return Region::kGlobal;
for (Region r : all())
if (code(r) == c) return r;
return std::nullopt;
}
std::optional<Region> Regions::from_residency(const std::string& residency) {
if (std::find(kResidency.begin(), kResidency.end(), residency) == kResidency.end())
return std::nullopt;
if (residency == "GLOBAL") return Region::kGlobal;
std::string c = residency.substr(0, residency.find('_'));
return parse(c);
}
const std::vector<std::string>& Regions::residency_values() { return kResidency; }
KeyKind KeyPolicy::classify(const std::string& key) {
if (key.empty()) return KeyKind::kNone;
return key.rfind(kAdminPrefix, 0) == 0 ? KeyKind::kAdmin : KeyKind::kProject;
}
void KeyPolicy::require_admin(const std::string& key) {
if (classify(key) == KeyKind::kProject)
throw llm::ApiError("openai", 401, "WRONG_KEY_KIND",
"OPENAI_ADMIN_KEY must hold an admin key (sk-admin-...); regular and "
"project keys are never sent to the organization API");
}
void KeyPolicy::require_project(const std::string& key) {
if (classify(key) == KeyKind::kAdmin)
throw llm::ApiError("openai", 401, "WRONG_KEY_KIND",
"OPENAI_API_KEY holds an admin key; webhook endpoints are managed "
"with the regular project key");
}
std::shared_ptr<AdminApiClient> AdminApiClient::with_transport(
std::unique_ptr<clients::Transport> transport, const std::string& key, Region region) {
KeyPolicy::require_admin(key);
return std::shared_ptr<AdminApiClient>(
new AdminApiClient(std::move(transport), make_config(kEnv, region), key));
}
std::shared_ptr<AdminApiClient> AdminApiClient::from_env(Region region) {
return with_transport(std::make_unique<clients::transports::HttpTransport>(),
llm::Config::get(kEnv), region);
}
std::shared_ptr<ProjectApiClient> ProjectApiClient::with_transport(
std::unique_ptr<clients::Transport> transport, const std::string& key, Region region) {
KeyPolicy::require_project(key);
return std::shared_ptr<ProjectApiClient>(
new ProjectApiClient(std::move(transport), make_config(kEnv, region), key));
}
std::shared_ptr<ProjectApiClient> ProjectApiClient::from_env(Region region) {
return with_transport(std::make_unique<clients::transports::HttpTransport>(),
llm::Config::get(kEnv), region);
}
} // namespace molo::openai::admin
+80
View File
@@ -0,0 +1,80 @@
#pragma once
// Credential-typed HTTP clients for the OpenAI administration surface.
//
// AdminApiClient organization administration: bearer OPENAI_ADMIN_KEY only.
// A key that is not an admin key ("sk-admin-...") is refused
// at construction (WRONG_KEY_KIND), so a regular or project
// key can never reach /organization/*.
// ProjectApiClient webhook endpoint management only: bearer OPENAI_API_KEY.
// OpenAI's spec secures /webhook_endpoints with the regular
// project key; an admin key is refused here.
//
// The two classes are distinct types and the services take one or the other,
// so the credential kind is checked by the compiler as well as at runtime.
#include <memory>
#include <optional>
#include <string>
#include <vector>
#include "llm/api_client.h"
namespace molo::openai::admin {
// Data residency: OpenAI serves each region from <code>.api.openai.com
// (every host below answered 401 on an unauthenticated probe, 2026-10-24).
enum class Region { kGlobal, kUs, kEu, kAu, kCa, kJp, kIn, kSg, kKr, kGb, kAe };
class Regions {
public:
static const std::vector<Region>& all();
static std::string code(Region region); // "" for global, "eu", "us", ...
static std::string base_url(Region region); // https://eu.api.openai.com/v1
static std::optional<Region> parse(const std::string& code); // "", "global" -> kGlobal
// Residency enum value of the spec ("EU_STORAGE_PROCESSING") -> the host region it implies.
static std::optional<Region> from_residency(const std::string& residency);
static const std::vector<std::string>& residency_values(); // PublicProjectResidency
};
enum class KeyKind { kNone, kAdmin, kProject };
class KeyPolicy {
public:
static constexpr const char* kAdminPrefix = "sk-admin-";
static KeyKind classify(const std::string& key);
// Throws ApiError 401 WRONG_KEY_KIND (never echoes the key).
static void require_admin(const std::string& key);
static void require_project(const std::string& key);
};
class AdminApiClient final : public llm::ApiClient {
public:
static constexpr const char* kEnv = "OPENAI_ADMIN_KEY";
// Key from llm::Config::get("OPENAI_ADMIN_KEY"); empty means not configured.
static std::shared_ptr<AdminApiClient> from_env(Region region = Region::kGlobal);
static std::shared_ptr<AdminApiClient> with_transport(
std::unique_ptr<clients::Transport> transport, const std::string& key,
Region region = Region::kGlobal);
private:
AdminApiClient(std::unique_ptr<clients::Transport> transport, llm::ApiClientConfig config,
std::string key)
: llm::ApiClient(std::move(transport), std::move(config), std::move(key)) {}
};
class ProjectApiClient final : public llm::ApiClient {
public:
static constexpr const char* kEnv = "OPENAI_API_KEY";
static std::shared_ptr<ProjectApiClient> from_env(Region region = Region::kGlobal);
static std::shared_ptr<ProjectApiClient> with_transport(
std::unique_ptr<clients::Transport> transport, const std::string& key,
Region region = Region::kGlobal);
private:
ProjectApiClient(std::unique_ptr<clients::Transport> transport, llm::ApiClientConfig config,
std::string key)
: llm::ApiClient(std::move(transport), std::move(config), std::move(key)) {}
};
} // namespace molo::openai::admin
+69
View File
@@ -0,0 +1,69 @@
#include "openai/admin/admin_service.h"
#include "openai/admin/caps.h"
#include "openai/admin/validate.h"
namespace molo::openai::admin {
AdminService::AdminService(std::shared_ptr<AdminApiClient> client)
: llm::Service(std::move(client)), auth_(AuthKind::kAdmin) {}
AdminService::AdminService(std::shared_ptr<ProjectApiClient> client)
: llm::Service(std::move(client)), auth_(AuthKind::kProject) {}
AdminService::Json AdminService::execute(Call call, const std::vector<std::string>& ids,
const Query& query, const Json* body, bool confirm) {
const CallSpec& spec = CallTable::spec(call);
if (CallTable::auth(call) != auth_)
Validate::fail(std::string(spec.key) + " needs a " + spec.auth +
" credential; this service holds the other kind");
if (CallTable::destructive(call)) Validate::confirmed(spec.key, confirm);
std::string path = CallTable::render(call, ids);
query.check_against(call);
Json checked;
const bool takes_body = spec.body_fields[0] != '\0';
if (takes_body) {
checked = body ? *body : Json::object();
if (!checked.is_object()) Validate::fail(std::string(spec.key) + " body must be an object");
for (const auto& [name, value] : checked.as_object()) {
(void)value;
if (!CallTable::allows_body_field(call, name))
Validate::fail(std::string(spec.key) + " has no body field " + name);
}
for (const std::string& req : CallTable::required_body_fields(call)) {
const Json* v = checked.find(req);
if (!v || v->is_null()) Validate::fail(std::string(spec.key) + " needs " + req);
}
if (checked.dump().size() > AdminCaps::kMaxBodyBytes) Validate::fail("request body over the cap");
} else if (body) {
Validate::fail(std::string(spec.key) + " takes no body");
}
path += query.encoded();
return client().request(CallTable::method(call), path, takes_body ? &checked : nullptr);
}
WalkResult AdminService::walk(Call call, const std::vector<std::string>& ids, const Query& base,
const std::string& cursor_param, const std::string& start_cursor) {
if (!CallTable::allows_query(call, cursor_param))
Validate::fail(std::string(CallTable::spec(call).key) + " cannot be walked with " + cursor_param);
return PageWalker::walk(
[&](const std::string& cursor) {
Query q = base;
if (!cursor.empty()) q.set(cursor_param, cursor);
return execute(call, ids, q);
},
start_cursor);
}
AdminService::Json AdminService::object_of(
std::initializer_list<std::pair<const char*, Json>> fields) {
Json o = Json::object();
for (const auto& [k, v] : fields)
if (!v.is_null()) o.set(k, v);
return o;
}
} // namespace molo::openai::admin
+46
View File
@@ -0,0 +1,46 @@
#pragma once
// Base of every resource service. One `execute` runs one row of the call
// table: it checks the credential kind of the call, refuses destructive calls
// without confirm=true, renders the path from validated ids, checks query
// names and body fields against the row, and sends the request. A service is
// built for one credential kind; running a call of the other kind throws.
#include <memory>
#include <string>
#include <vector>
#include "clients/body/json.h"
#include "llm/api_client.h"
#include "openai/admin/admin_client.h"
#include "openai/admin/calls.h"
#include "openai/admin/page.h"
#include "openai/admin/query.h"
namespace molo::openai::admin {
class AdminService : public llm::Service {
public:
using Json = clients::body::Json;
AuthKind auth_kind() const { return auth_; }
protected:
AdminService(std::shared_ptr<AdminApiClient> client);
AdminService(std::shared_ptr<ProjectApiClient> client);
// Runs one table row. `ids` fill the {placeholders} in order. `body` must be
// an object whose keys are allowed by the row and cover its required fields.
Json execute(Call call, const std::vector<std::string>& ids = {}, const Query& query = {},
const Json* body = nullptr, bool confirm = false);
// A cursor list walked to the page / item ceilings (WalkResult::truncated).
WalkResult walk(Call call, const std::vector<std::string>& ids, const Query& base,
const std::string& cursor_param, const std::string& start_cursor = "");
static Json object_of(std::initializer_list<std::pair<const char*, Json>> fields);
private:
AuthKind auth_;
};
} // namespace molo::openai::admin
+87
View File
@@ -0,0 +1,87 @@
#include "openai/admin/audit_events.h"
#include <algorithm>
#include <iterator>
namespace molo::openai::admin {
// AUDIT-EVENTS-BEGIN (AuditLogEventType enum; checked by tools/check_spec.py)
static const char* const kAuditEvents[] = {
"api_key.created", "api_key.updated", "api_key.deleted", "certificate.created",
"certificate.updated", "certificate.deleted", "certificates.activated",
"certificates.deactivated", "checkpoint.permission.created", "checkpoint.permission.deleted",
"external_key.registered", "external_key.removed", "external_storage.registered",
"external_storage.removed", "group.created", "group.updated", "group.deleted", "invite.sent",
"invite.accepted", "invite.deleted", "ip_allowlist.created", "ip_allowlist.updated",
"ip_allowlist.deleted", "ip_allowlist.config.activated", "ip_allowlist.config.deactivated",
"login.succeeded", "login.failed", "logout.succeeded", "logout.failed", "organization.updated",
"project.created", "project.updated", "project.archived", "project.deleted",
"rate_limit.updated", "rate_limit.deleted", "resource.deleted", "tunnel.created",
"tunnel.updated", "tunnel.deleted", "workload_identity_provider.created",
"workload_identity_provider.updated", "workload_identity_provider.deleted",
"workload_identity_provider_mapping.created", "workload_identity_provider_mapping.updated",
"workload_identity_provider_mapping.deleted", "role.created", "role.updated", "role.deleted",
"role.assignment.created", "role.assignment.deleted", "role.bound_to_resource",
"role.unbound_from_resource", "scim.enabled", "scim.disabled", "service_account.created",
"service_account.updated", "service_account.deleted", "user.added", "user.updated",
"user.deleted", "tenant.metadata.updated", "tenant.microsoft_entra_mapping.upserted",
"tenant.microsoft_entra_mapping.deleted", "tenant.workload_identity.provider.created",
"tenant.workload_identity.provider.updated", "tenant.workload_identity.provider.archived",
"tenant.workload_identity.mapping.created", "tenant.workload_identity.mapping.updated",
"tenant.workload_identity.mapping.archived", "tenant.workload_identity.binding.created",
"tenant.workload_identity.principal.provisioned",
"tenant.workload_identity.access_token.issued", "tenant.admin_api_key.created",
"tenant.admin_api_key.updated", "tenant.admin_api_key.deleted",
"tenant.project_api_key.created", "tenant.trusted_access.business_verification.started",
"tenant.trusted_access.application.submitted", "tenant.chatgpt_access_token.revoked",
"tenant.migration.completed", "tenant.sso.migrated", "tenant.domains.migrated",
"tenant.sso_connection.created", "tenant.sso_connection.updated",
"tenant.sso_connection.deleted", "tenant.sso_connection.setup.started",
"tenant.policy.created", "tenant.policy.updated", "tenant.policy.deleted",
"tenant.policy.attached", "tenant.policy.detached",
"tenant.principal_authentication_policy.resolved", "tenant.scim.setup.started",
"tenant.scim.deletion.requested", "tenant.scim.directory.created",
"tenant.product_access_policy.updated", "tenant.resource_share_grant.created",
"tenant.resource_share_grant.updated", "tenant.resource_share_grant.accepted",
"tenant.resource_share_grant.declined", "tenant.resource_share_grant.revoked",
"tenant.resource_share_grant.deleted", "tenant.service_account.updated",
"tenant.service_account.deleted", "tenant.service_account.token.revoked",
"tenant.billing.overage_limit.updated", "tenant.billing.alerts.updated",
"tenant.billing.info.updated", "tenant.usage_limit.workspace.updated",
"tenant.usage_limit.group.updated", "tenant.usage_limit.user.updated",
"tenant.usage_limit.increase_request.updated", "tenant.usage_limit.increase_request.resolved",
"tenant.group.created", "tenant.group.updated", "tenant.group.deleted",
"tenant.group.member.added", "tenant.group.member.removed",
"tenant.migration_rollout.status.updated", "tenant.migration_rollout.tier.updated",
"tenant.role.metadata.updated", "tenant.custom_role.created", "tenant.custom_role.updated",
"tenant.custom_role.deleted", "tenant.role_assignment.created",
"tenant.role_assignment.deleted", "tenant.resource_role_assignment.created",
"tenant.resource_role_assignment.deleted", "tenant.resource_access.updated",
"tenant.resource_access.deleted", "tenant.ads_account.onboarding.redemption",
"tenant.session_policy.created", "tenant.session_policy.updated",
"tenant.session_policy.deleted", "tenant.session_revocation.started",
"tenant.third_party_app_policy.updated", "tenant.user.added", "tenant.user.updated",
"tenant.user.removed", "tenant.user.looked_up", "tenant.user.invited",
"tenant.membership.revoked", "tenant.api_organization_invite.upserted",
"tenant.api_organization_invite.deleted", "tenant.chatgpt_workspace_invite.upserted",
"tenant.membership.accepted", "tenant.membership.declined",
"tenant.workspace_invite_email_settings.updated",
};
// AUDIT-EVENTS-END
const std::vector<std::string>& AuditEventCatalog::all() {
static const std::vector<std::string> events(std::begin(kAuditEvents), std::end(kAuditEvents));
return events;
}
bool AuditEventCatalog::known(const std::string& type) {
const auto& events = all();
return std::find(events.begin(), events.end(), type) != events.end();
}
std::string AuditEventCatalog::family(const std::string& type) {
const std::size_t dot = type.find('.');
return dot == std::string::npos ? type : type.substr(0, dot);
}
} // namespace molo::openai::admin
+20
View File
@@ -0,0 +1,20 @@
#pragma once
// The audit log event type catalog: the `AuditLogEventType` enum of OpenAI's
// OpenAPI document, one string per type. `type` filters are validated against
// it before any request is sent.
#include <string>
#include <vector>
namespace molo::openai::admin {
class AuditEventCatalog {
public:
static const std::vector<std::string>& all();
static bool known(const std::string& type);
// Prefix before the first dot ("api_key", "project", "tenant", ...).
static std::string family(const std::string& type);
};
} // namespace molo::openai::admin
+51
View File
@@ -0,0 +1,51 @@
#include "openai/admin/audit_log.h"
#include "openai/admin/caps.h"
#include "openai/admin/validate.h"
namespace molo::openai::admin {
Query AuditQuery::to_query() const {
Query q;
const std::pair<const char*, const std::optional<std::int64_t>*> times[] = {
{"effective_at[gt]", &effective_at_gt}, {"effective_at[gte]", &effective_at_gte},
{"effective_at[lt]", &effective_at_lt}, {"effective_at[lte]", &effective_at_lte}};
for (const auto& [name, value] : times) {
if (!*value) continue;
Validate::epoch(name, **value);
q.set_int(name, **value);
}
if (effective_at_gt && effective_at_gte) Validate::fail("give effective_at gt or gte, not both");
if (effective_at_lt && effective_at_lte) Validate::fail("give effective_at lt or lte, not both");
q.add_all("project_ids[]", project_ids);
Validate::count("event_types", event_types.size(), AdminCaps::kMaxAuditEventTypes, true);
for (const std::string& t : event_types)
if (!AuditEventCatalog::known(t)) Validate::fail("unknown audit event type " + t);
q.add_all("event_types[]", event_types);
q.add_all("actor_ids[]", actor_ids);
for (const std::string& e : actor_emails) Validate::email(e);
q.add_all("actor_emails[]", actor_emails);
q.add_all("resource_ids[]", resource_ids);
if (tenant_only) q.set_bool("tenant_only", *tenant_only);
if (limit) {
Validate::range("limit", *limit, 1, AdminCaps::kMaxPageLimit);
q.set_int("limit", *limit);
}
if (!after.empty() && !before.empty()) Validate::fail("give after or before, not both");
if (!after.empty()) q.set("after", after);
if (!before.empty()) q.set("before", before);
return q;
}
AdminService::Json AuditLogs::list(const AuditQuery& query) {
return execute(Call::kAuditLogsList, {}, query.to_query());
}
WalkResult AuditLogs::walk(const AuditQuery& query) {
AuditQuery first = query;
first.after.clear();
if (!first.before.empty()) Validate::fail("walk follows after; clear before");
return AdminService::walk(Call::kAuditLogsList, {}, first.to_query(), "after", query.after);
}
} // namespace molo::openai::admin
+37
View File
@@ -0,0 +1,37 @@
#pragma once
// Audit logs: `GET /organization/audit_logs` with every documented filter and
// the event type catalog (AuditEventCatalog, 149 types in the pinned spec).
// Array filters use the bracket names the spec declares (`event_types[]`),
// `effective_at` is sent as effective_at[gt|gte|lt|lte]. Paging is by id:
// `after` / `before` take an audit log id.
#include <optional>
#include <string>
#include <vector>
#include "openai/admin/admin_service.h"
#include "openai/admin/audit_events.h"
namespace molo::openai::admin {
struct AuditQuery {
std::optional<std::int64_t> effective_at_gt, effective_at_gte, effective_at_lt, effective_at_lte;
std::vector<std::string> project_ids, event_types, actor_ids, actor_emails, resource_ids;
std::optional<bool> tenant_only;
std::optional<int> limit; // 1..100
std::string after, before;
Query to_query() const;
};
class AuditLogs : public AdminService {
public:
explicit AuditLogs(std::shared_ptr<AdminApiClient> client) : AdminService(std::move(client)) {}
Json list(const AuditQuery& query = {});
// Follows `after` up to the page / item ceilings; truncation is reported.
WalkResult walk(const AuditQuery& query);
static const std::vector<std::string>& event_types() { return AuditEventCatalog::all(); }
};
} // namespace molo::openai::admin
+14
View File
@@ -0,0 +1,14 @@
#include "openai/admin/call_runner.h"
#include "openai/admin/validate.h"
namespace molo::openai::admin {
AdminService::Json CallRunner::run(const std::string& key, const std::vector<std::string>& ids,
const Query& query, const Json* body, bool confirm) {
const CallSpec* spec = CallTable::find(key);
if (!spec) Validate::fail("unknown call " + key);
return execute(spec->call, ids, query, body, confirm);
}
} // namespace molo::openai::admin
+25
View File
@@ -0,0 +1,25 @@
#pragma once
// Runs any row of the call table by its key ("projects.users.list"). Same
// guards as the typed services (credential kind, confirm for destructive
// rows, id and body validation, query names from the table). Used by the
// example's generic routes; typed code should use the resource services.
#include <string>
#include <vector>
#include "openai/admin/admin_service.h"
namespace molo::openai::admin {
class CallRunner : public AdminService {
public:
explicit CallRunner(std::shared_ptr<AdminApiClient> client) : AdminService(std::move(client)) {}
explicit CallRunner(std::shared_ptr<ProjectApiClient> client) : AdminService(std::move(client)) {}
// Throws ApiError::invalid for an unknown key.
Json run(const std::string& key, const std::vector<std::string>& ids, const Query& query,
const Json* body, bool confirm);
};
} // namespace molo::openai::admin
+352
View File
@@ -0,0 +1,352 @@
#include "openai/admin/calls.h"
#include <cstring>
#include "llm/api_client.h"
#include "llm/error.h"
namespace molo::openai::admin {
namespace {
constexpr const char* kVendor = "openai";
}
// CALLS-BEGIN (parsed by tools/check_spec.py; one row per line)
static const CallSpec kCalls[] = {
{Call::kAdminApiKeysList, "admin_api_keys.list", "GET", "/organization/admin_api_keys", "admin-api-keys-list", "admin", "", "", "after,order,limit", "", "ApiKeyList", ""},
{Call::kAdminApiKeysCreate, "admin_api_keys.create", "POST", "/organization/admin_api_keys", "admin-api-keys-create", "admin", "name,expires_in_seconds", "name", "", "", "AdminApiKeyCreateResponse", ""},
{Call::kAdminApiKeysGet, "admin_api_keys.get", "GET", "/organization/admin_api_keys/{key_id}", "admin-api-keys-get", "admin", "", "", "", "", "AdminApiKey", ""},
{Call::kAdminApiKeysDelete, "admin_api_keys.delete", "DELETE", "/organization/admin_api_keys/{key_id}", "admin-api-keys-delete", "admin", "", "", "", "", "", "destructive"},
{Call::kAuditLogsList, "audit_logs.list", "GET", "/organization/audit_logs", "list-audit-logs", "admin", "", "", "effective_at,project_ids[],event_types[],actor_ids[],actor_emails[],resource_ids[],tenant_only,limit,after,before", "", "ListAuditLogsResponse", ""},
{Call::kCertificatesList, "certificates.list", "GET", "/organization/certificates", "listOrganizationCertificates", "admin", "", "", "limit,after,order", "", "ListCertificatesResponse", ""},
{Call::kCertificatesCreate, "certificates.create", "POST", "/organization/certificates", "uploadCertificate", "admin", "name,certificate", "certificate", "", "UploadCertificateRequest", "Certificate", ""},
{Call::kCertificatesActivate, "certificates.activate", "POST", "/organization/certificates/activate", "activateOrganizationCertificates", "admin", "certificate_ids", "certificate_ids", "", "ToggleCertificatesRequest", "OrganizationCertificateActivationResponse", ""},
{Call::kCertificatesDeactivate, "certificates.deactivate", "POST", "/organization/certificates/deactivate", "deactivateOrganizationCertificates", "admin", "certificate_ids", "certificate_ids", "", "ToggleCertificatesRequest", "OrganizationCertificateDeactivationResponse", "destructive"},
{Call::kCertificatesGet, "certificates.get", "GET", "/organization/certificates/{certificate_id}", "getCertificate", "admin", "", "", "include", "", "Certificate", ""},
{Call::kCertificatesUpdate, "certificates.update", "POST", "/organization/certificates/{certificate_id}", "modifyCertificate", "admin", "name", "", "", "ModifyCertificateRequest", "Certificate", ""},
{Call::kCertificatesDelete, "certificates.delete", "DELETE", "/organization/certificates/{certificate_id}", "deleteCertificate", "admin", "", "", "", "", "DeleteCertificateResponse", "destructive"},
{Call::kCosts, "costs", "GET", "/organization/costs", "usage-costs", "admin", "", "", "start_time,end_time,bucket_width,project_ids,api_key_ids,line_items,group_by,limit,page", "", "UsageResponse", ""},
{Call::kDataRetentionGet, "data_retention.get", "GET", "/organization/data_retention", "retrieve-organization-data-retention", "admin", "", "", "", "", "OrganizationDataRetention", ""},
{Call::kDataRetentionUpdate, "data_retention.update", "POST", "/organization/data_retention", "update-organization-data-retention", "admin", "retention_type", "retention_type", "", "UpdateOrganizationDataRetentionBody", "OrganizationDataRetention", "destructive"},
{Call::kGroupsList, "groups.list", "GET", "/organization/groups", "list-groups", "admin", "", "", "limit,after,order", "", "GroupListResource", ""},
{Call::kGroupsCreate, "groups.create", "POST", "/organization/groups", "create-group", "admin", "name", "name", "", "CreateGroupBody", "GroupResponse", ""},
{Call::kGroupsGet, "groups.get", "GET", "/organization/groups/{group_id}", "retrieve-group", "admin", "", "", "", "", "GroupResponse", ""},
{Call::kGroupsUpdate, "groups.update", "POST", "/organization/groups/{group_id}", "update-group", "admin", "name", "name", "", "UpdateGroupBody", "GroupResourceWithSuccess", ""},
{Call::kGroupsDelete, "groups.delete", "DELETE", "/organization/groups/{group_id}", "delete-group", "admin", "", "", "", "", "GroupDeletedResource", "destructive"},
{Call::kGroupsRolesList, "groups.roles.list", "GET", "/organization/groups/{group_id}/roles", "list-group-role-assignments", "admin", "", "", "limit,after,order", "", "RoleListResource", ""},
{Call::kGroupsRolesCreate, "groups.roles.create", "POST", "/organization/groups/{group_id}/roles", "assign-group-role", "admin", "role_id", "role_id", "", "PublicAssignOrganizationGroupRoleBody", "GroupRoleAssignment", ""},
{Call::kGroupsRolesGet, "groups.roles.get", "GET", "/organization/groups/{group_id}/roles/{role_id}", "retrieve-group-role", "admin", "", "", "", "", "AssignedRoleDetails", ""},
{Call::kGroupsRolesDelete, "groups.roles.delete", "DELETE", "/organization/groups/{group_id}/roles/{role_id}", "unassign-group-role", "admin", "", "", "", "", "DeletedRoleAssignmentResource", "destructive"},
{Call::kGroupsUsersList, "groups.users.list", "GET", "/organization/groups/{group_id}/users", "list-group-users", "admin", "", "", "limit,after,order", "", "UserListResource", ""},
{Call::kGroupsUsersCreate, "groups.users.create", "POST", "/organization/groups/{group_id}/users", "add-group-user", "admin", "user_id", "user_id", "", "CreateGroupUserBody", "GroupUserAssignment", ""},
{Call::kGroupsUsersGet, "groups.users.get", "GET", "/organization/groups/{group_id}/users/{user_id}", "retrieve-group-user", "admin", "", "", "", "", "GroupMemberUser", ""},
{Call::kGroupsUsersDelete, "groups.users.delete", "DELETE", "/organization/groups/{group_id}/users/{user_id}", "remove-group-user", "admin", "", "", "", "", "GroupUserDeletedResource", "destructive"},
{Call::kInvitesList, "invites.list", "GET", "/organization/invites", "list-invites", "admin", "", "", "limit,after", "", "InviteListResponse", ""},
{Call::kInvitesCreate, "invites.create", "POST", "/organization/invites", "inviteUser", "admin", "email,role,projects", "email,role", "", "InviteRequest", "Invite", ""},
{Call::kInvitesGet, "invites.get", "GET", "/organization/invites/{invite_id}", "retrieve-invite", "admin", "", "", "", "", "Invite", ""},
{Call::kInvitesDelete, "invites.delete", "DELETE", "/organization/invites/{invite_id}", "delete-invite", "admin", "", "", "", "", "InviteDeleteResponse", "destructive"},
{Call::kProjectsList, "projects.list", "GET", "/organization/projects", "list-projects", "admin", "", "", "limit,after,include_archived", "", "ProjectListResponse", ""},
{Call::kProjectsCreate, "projects.create", "POST", "/organization/projects", "create-project", "admin", "name,geography,residency,external_key_id", "name", "", "ProjectCreateRequest", "Project", ""},
{Call::kProjectsGet, "projects.get", "GET", "/organization/projects/{project_id}", "retrieve-project", "admin", "", "", "", "", "Project", ""},
{Call::kProjectsUpdate, "projects.update", "POST", "/organization/projects/{project_id}", "modify-project", "admin", "name,external_key_id,geography", "", "", "ProjectUpdateRequest", "Project", ""},
{Call::kProjectsApiKeysList, "projects.api_keys.list", "GET", "/organization/projects/{project_id}/api_keys", "list-project-api-keys", "admin", "", "", "limit,after,owner_project_access", "", "ProjectApiKeyListResponse", ""},
{Call::kProjectsApiKeysGet, "projects.api_keys.get", "GET", "/organization/projects/{project_id}/api_keys/{api_key_id}", "retrieve-project-api-key", "admin", "", "", "", "", "ProjectApiKey", ""},
{Call::kProjectsApiKeysUpdate, "projects.api_keys.update", "POST", "/organization/projects/{project_id}/api_keys/{api_key_id}", "update-project-api-key", "admin", "expires_in_seconds,scopes", "", "", "UpdateProjectApiKeyBody", "ProjectApiKey", ""},
{Call::kProjectsApiKeysDelete, "projects.api_keys.delete", "DELETE", "/organization/projects/{project_id}/api_keys/{api_key_id}", "delete-project-api-key", "admin", "", "", "", "", "ProjectApiKeyDeleteResponse", "destructive"},
{Call::kProjectsArchive, "projects.archive", "POST", "/organization/projects/{project_id}/archive", "archive-project", "admin", "", "", "", "", "Project", "destructive"},
{Call::kProjectsCertificatesList, "projects.certificates.list", "GET", "/organization/projects/{project_id}/certificates", "listProjectCertificates", "admin", "", "", "limit,after,order", "", "ListProjectCertificatesResponse", ""},
{Call::kProjectsCertificatesActivate, "projects.certificates.activate", "POST", "/organization/projects/{project_id}/certificates/activate", "activateProjectCertificates", "admin", "certificate_ids", "certificate_ids", "", "ToggleCertificatesRequest", "OrganizationProjectCertificateActivationResponse", ""},
{Call::kProjectsCertificatesDeactivate, "projects.certificates.deactivate", "POST", "/organization/projects/{project_id}/certificates/deactivate", "deactivateProjectCertificates", "admin", "certificate_ids", "certificate_ids", "", "ToggleCertificatesRequest", "OrganizationProjectCertificateDeactivationResponse", "destructive"},
{Call::kProjectsDataRetentionGet, "projects.data_retention.get", "GET", "/organization/projects/{project_id}/data_retention", "retrieve-project-data-retention", "admin", "", "", "", "", "ProjectDataRetention", ""},
{Call::kProjectsDataRetentionUpdate, "projects.data_retention.update", "POST", "/organization/projects/{project_id}/data_retention", "update-project-data-retention", "admin", "retention_type", "retention_type", "", "UpdateProjectDataRetentionBody", "ProjectDataRetention", "destructive"},
{Call::kProjectsGroupsList, "projects.groups.list", "GET", "/organization/projects/{project_id}/groups", "list-project-groups", "admin", "", "", "limit,after,order", "", "ProjectGroupListResource", ""},
{Call::kProjectsGroupsCreate, "projects.groups.create", "POST", "/organization/projects/{project_id}/groups", "add-project-group", "admin", "group_id,role", "group_id,role", "", "InviteProjectGroupBody", "ProjectGroup", ""},
{Call::kProjectsGroupsGet, "projects.groups.get", "GET", "/organization/projects/{project_id}/groups/{group_id}", "retrieve-project-group", "admin", "", "", "group_type", "", "ProjectGroup", ""},
{Call::kProjectsGroupsDelete, "projects.groups.delete", "DELETE", "/organization/projects/{project_id}/groups/{group_id}", "remove-project-group", "admin", "", "", "", "", "ProjectGroupDeletedResource", "destructive"},
{Call::kProjectsHostedToolPermissionsGet, "projects.hosted_tool_permissions.get", "GET", "/organization/projects/{project_id}/hosted_tool_permissions", "retrieve-project-hosted-tool-permissions", "admin", "", "", "", "", "ProjectHostedToolPermissions", ""},
{Call::kProjectsHostedToolPermissionsUpdate, "projects.hosted_tool_permissions.update", "POST", "/organization/projects/{project_id}/hosted_tool_permissions", "update-project-hosted-tool-permissions", "admin", "file_search,web_search,image_generation,mcp,code_interpreter", "", "", "ProjectHostedToolPermissionsUpdateRequest", "ProjectHostedToolPermissions", ""},
{Call::kProjectsModelPermissionsGet, "projects.model_permissions.get", "GET", "/organization/projects/{project_id}/model_permissions", "retrieve-project-model-permissions", "admin", "", "", "", "", "ProjectModelPermissions", ""},
{Call::kProjectsModelPermissionsUpdate, "projects.model_permissions.update", "POST", "/organization/projects/{project_id}/model_permissions", "update-project-model-permissions", "admin", "mode,model_ids", "mode,model_ids", "", "ProjectModelPermissionsUpdateRequest", "ProjectModelPermissions", ""},
{Call::kProjectsModelPermissionsDelete, "projects.model_permissions.delete", "DELETE", "/organization/projects/{project_id}/model_permissions", "delete-project-model-permissions", "admin", "", "", "", "", "ProjectModelPermissionsDeleteResponse", "destructive"},
{Call::kProjectsRateLimitsList, "projects.rate_limits.list", "GET", "/organization/projects/{project_id}/rate_limits", "list-project-rate-limits", "admin", "", "", "limit,after,before", "", "ProjectRateLimitListResponse", ""},
{Call::kProjectsRateLimitsUpdate, "projects.rate_limits.update", "POST", "/organization/projects/{project_id}/rate_limits/{rate_limit_id}", "update-project-rate-limits", "admin", "max_requests_per_1_minute,max_tokens_per_1_minute,max_images_per_1_minute,max_audio_megabytes_per_1_minute,max_requests_per_1_day,batch_1_day_max_input_tokens", "", "", "ProjectRateLimitUpdateRequest", "ProjectRateLimit", ""},
{Call::kProjectsServiceAccountsList, "projects.service_accounts.list", "GET", "/organization/projects/{project_id}/service_accounts", "list-project-service-accounts", "admin", "", "", "limit,after", "", "ProjectServiceAccountListResponse", ""},
{Call::kProjectsServiceAccountsCreate, "projects.service_accounts.create", "POST", "/organization/projects/{project_id}/service_accounts", "create-project-service-account", "admin", "name,create_service_account_only,expires_in_seconds", "name", "", "ProjectServiceAccountCreateRequest", "ProjectServiceAccountCreateResponse", ""},
{Call::kProjectsServiceAccountsGet, "projects.service_accounts.get", "GET", "/organization/projects/{project_id}/service_accounts/{service_account_id}", "retrieve-project-service-account", "admin", "", "", "", "", "ProjectServiceAccount", ""},
{Call::kProjectsServiceAccountsUpdate, "projects.service_accounts.update", "POST", "/organization/projects/{project_id}/service_accounts/{service_account_id}", "update-project-service-account", "admin", "name,role", "", "", "UpdateProjectServiceAccountBody", "ProjectServiceAccount", ""},
{Call::kProjectsServiceAccountsDelete, "projects.service_accounts.delete", "DELETE", "/organization/projects/{project_id}/service_accounts/{service_account_id}", "delete-project-service-account", "admin", "", "", "", "", "ProjectServiceAccountDeleteResponse", "destructive"},
{Call::kProjectsSpendAlertsList, "projects.spend_alerts.list", "GET", "/organization/projects/{project_id}/spend_alerts", "list-project-spend-alerts", "admin", "", "", "limit,order,after,before", "", "ProjectSpendAlertListResource", ""},
{Call::kProjectsSpendAlertsCreate, "projects.spend_alerts.create", "POST", "/organization/projects/{project_id}/spend_alerts", "create-project-spend-alert", "admin", "threshold_amount,currency,interval,notification_channel", "threshold_amount,currency,interval,notification_channel", "", "CreateSpendAlertBody", "ProjectSpendAlert", ""},
{Call::kProjectsSpendAlertsGet, "projects.spend_alerts.get", "GET", "/organization/projects/{project_id}/spend_alerts/{alert_id}", "retrieve-project-spend-alert", "admin", "", "", "", "", "ProjectSpendAlert", ""},
{Call::kProjectsSpendAlertsUpdate, "projects.spend_alerts.update", "POST", "/organization/projects/{project_id}/spend_alerts/{alert_id}", "update-project-spend-alert", "admin", "threshold_amount,currency,interval,notification_channel", "threshold_amount,currency,interval,notification_channel", "", "CreateSpendAlertBody", "ProjectSpendAlert", ""},
{Call::kProjectsSpendAlertsDelete, "projects.spend_alerts.delete", "DELETE", "/organization/projects/{project_id}/spend_alerts/{alert_id}", "delete-project-spend-alert", "admin", "", "", "", "", "ProjectSpendAlertDeletedResource", "destructive"},
{Call::kProjectsUsersList, "projects.users.list", "GET", "/organization/projects/{project_id}/users", "list-project-users", "admin", "", "", "limit,after", "", "ProjectUserListResponse", ""},
{Call::kProjectsUsersCreate, "projects.users.create", "POST", "/organization/projects/{project_id}/users", "create-project-user", "admin", "user_id,email,role", "role", "", "ProjectUserCreateRequest", "ProjectUser", ""},
{Call::kProjectsUsersGet, "projects.users.get", "GET", "/organization/projects/{project_id}/users/{user_id}", "retrieve-project-user", "admin", "", "", "", "", "ProjectUser", ""},
{Call::kProjectsUsersUpdate, "projects.users.update", "POST", "/organization/projects/{project_id}/users/{user_id}", "modify-project-user", "admin", "role", "", "", "ProjectUserUpdateRequest", "ProjectUser", ""},
{Call::kProjectsUsersDelete, "projects.users.delete", "DELETE", "/organization/projects/{project_id}/users/{user_id}", "delete-project-user", "admin", "", "", "", "", "ProjectUserDeleteResponse", "destructive"},
{Call::kRolesList, "roles.list", "GET", "/organization/roles", "list-roles", "admin", "", "", "limit,after,order", "", "PublicRoleListResource", ""},
{Call::kRolesCreate, "roles.create", "POST", "/organization/roles", "create-role", "admin", "role_name,permissions,description", "role_name,permissions", "", "PublicCreateOrganizationRoleBody", "Role", ""},
{Call::kRolesGet, "roles.get", "GET", "/organization/roles/{role_id}", "retrieve-role", "admin", "", "", "", "", "Role", ""},
{Call::kRolesUpdate, "roles.update", "POST", "/organization/roles/{role_id}", "update-role", "admin", "permissions,description,role_name", "", "", "PublicUpdateOrganizationRoleBody", "Role", ""},
{Call::kRolesDelete, "roles.delete", "DELETE", "/organization/roles/{role_id}", "delete-role", "admin", "", "", "", "", "RoleDeletedResource", "destructive"},
{Call::kSpendAlertsList, "spend_alerts.list", "GET", "/organization/spend_alerts", "list-organization-spend-alerts", "admin", "", "", "limit,order,after,before", "", "OrganizationSpendAlertListResource", ""},
{Call::kSpendAlertsCreate, "spend_alerts.create", "POST", "/organization/spend_alerts", "create-organization-spend-alert", "admin", "threshold_amount,currency,interval,notification_channel", "threshold_amount,currency,interval,notification_channel", "", "CreateSpendAlertBody", "OrganizationSpendAlert", ""},
{Call::kSpendAlertsGet, "spend_alerts.get", "GET", "/organization/spend_alerts/{alert_id}", "retrieve-organization-spend-alert", "admin", "", "", "", "", "OrganizationSpendAlert", ""},
{Call::kSpendAlertsUpdate, "spend_alerts.update", "POST", "/organization/spend_alerts/{alert_id}", "update-organization-spend-alert", "admin", "threshold_amount,currency,interval,notification_channel", "threshold_amount,currency,interval,notification_channel", "", "CreateSpendAlertBody", "OrganizationSpendAlert", ""},
{Call::kSpendAlertsDelete, "spend_alerts.delete", "DELETE", "/organization/spend_alerts/{alert_id}", "delete-organization-spend-alert", "admin", "", "", "", "", "OrganizationSpendAlertDeletedResource", "destructive"},
{Call::kUsageAudioSpeeches, "usage.audio_speeches", "GET", "/organization/usage/audio_speeches", "usage-audio-speeches", "admin", "", "", "start_time,end_time,bucket_width,project_ids,user_ids,api_key_ids,models,group_by,limit,page", "", "UsageResponse", ""},
{Call::kUsageAudioTranscriptions, "usage.audio_transcriptions", "GET", "/organization/usage/audio_transcriptions", "usage-audio-transcriptions", "admin", "", "", "start_time,end_time,bucket_width,project_ids,user_ids,api_key_ids,models,group_by,limit,page", "", "UsageResponse", ""},
{Call::kUsageCodeInterpreterSessions, "usage.code_interpreter_sessions", "GET", "/organization/usage/code_interpreter_sessions", "usage-code-interpreter-sessions", "admin", "", "", "start_time,end_time,bucket_width,project_ids,group_by,limit,page", "", "UsageResponse", ""},
{Call::kUsageCompletions, "usage.completions", "GET", "/organization/usage/completions", "usage-completions", "admin", "", "", "start_time,end_time,bucket_width,project_ids,user_ids,api_key_ids,models,batch,group_by,limit,page", "", "UsageResponse", ""},
{Call::kUsageEmbeddings, "usage.embeddings", "GET", "/organization/usage/embeddings", "usage-embeddings", "admin", "", "", "start_time,end_time,bucket_width,project_ids,user_ids,api_key_ids,models,group_by,limit,page", "", "UsageResponse", ""},
{Call::kUsageFileSearchCalls, "usage.file_search_calls", "GET", "/organization/usage/file_search_calls", "usage-file-search-calls", "admin", "", "", "start_time,end_time,bucket_width,project_ids,user_ids,api_key_ids,vector_store_ids,group_by,limit,page", "", "UsageResponse", ""},
{Call::kUsageImages, "usage.images", "GET", "/organization/usage/images", "usage-images", "admin", "", "", "start_time,end_time,bucket_width,sources,sizes,project_ids,user_ids,api_key_ids,models,group_by,limit,page", "", "UsageResponse", ""},
{Call::kUsageModerations, "usage.moderations", "GET", "/organization/usage/moderations", "usage-moderations", "admin", "", "", "start_time,end_time,bucket_width,project_ids,user_ids,api_key_ids,models,group_by,limit,page", "", "UsageResponse", ""},
{Call::kUsageVectorStores, "usage.vector_stores", "GET", "/organization/usage/vector_stores", "usage-vector-stores", "admin", "", "", "start_time,end_time,bucket_width,project_ids,group_by,limit,page", "", "UsageResponse", ""},
{Call::kUsageWebSearchCalls, "usage.web_search_calls", "GET", "/organization/usage/web_search_calls", "usage-web-search-calls", "admin", "", "", "start_time,end_time,bucket_width,project_ids,user_ids,api_key_ids,models,context_levels,group_by,limit,page", "", "UsageResponse", ""},
{Call::kUsersList, "users.list", "GET", "/organization/users", "list-users", "admin", "", "", "limit,after,emails", "", "UserListResponse", ""},
{Call::kUsersGet, "users.get", "GET", "/organization/users/{user_id}", "retrieve-user", "admin", "", "", "", "", "User", ""},
{Call::kUsersUpdate, "users.update", "POST", "/organization/users/{user_id}", "modify-user", "admin", "role,role_id,technical_level,developer_persona", "", "", "UserRoleUpdateRequest", "User", ""},
{Call::kUsersDelete, "users.delete", "DELETE", "/organization/users/{user_id}", "delete-user", "admin", "", "", "", "", "UserDeleteResponse", "destructive"},
{Call::kUsersRolesList, "users.roles.list", "GET", "/organization/users/{user_id}/roles", "list-user-role-assignments", "admin", "", "", "limit,after,order", "", "RoleListResource", ""},
{Call::kUsersRolesCreate, "users.roles.create", "POST", "/organization/users/{user_id}/roles", "assign-user-role", "admin", "role_id", "role_id", "", "PublicAssignOrganizationGroupRoleBody", "UserRoleAssignment", ""},
{Call::kUsersRolesGet, "users.roles.get", "GET", "/organization/users/{user_id}/roles/{role_id}", "retrieve-user-role", "admin", "", "", "", "", "AssignedRoleDetails", ""},
{Call::kUsersRolesDelete, "users.roles.delete", "DELETE", "/organization/users/{user_id}/roles/{role_id}", "unassign-user-role", "admin", "", "", "", "", "DeletedRoleAssignmentResource", "destructive"},
{Call::kUsageDecisions, "usage.decisions", "GET", "/organization/usage/decisions", "OrganizationDecisionsusage", "admin", "", "", "start_time,end_time,bucket_width,limit,page,project_ids,group_by,user_ids,api_key_ids,models,batch", "", "PublicDecisionsUsageResponseResource", ""},
{Call::kExternalStorageList, "external_storage.list", "GET", "/organization/external_storage", "Listexternalstorageconfigurations", "admin", "", "", "project_id,after,order,limit", "", "ExternalStorageListResource", ""},
{Call::kExternalStorageCreate, "external_storage.create", "POST", "/organization/external_storage", "Createanexternalstorageconfiguration", "admin", "project_id,provider", "project_id,provider", "", "CreateExternalStorageBody", "ExternalStorageResponse", ""},
{Call::kExternalStorageGet, "external_storage.get", "GET", "/organization/external_storage/{external_storage_id}", "Getanexternalstorageconfiguration", "admin", "", "", "", "", "ExternalStorageResponse", ""},
{Call::kExternalStorageDelete, "external_storage.delete", "DELETE", "/organization/external_storage/{external_storage_id}", "Deleteanexternalstorageconfiguration", "admin", "", "", "", "", "ExternalStorageDeletedResource", "destructive"},
{Call::kExternalStorageValidate, "external_storage.validate", "POST", "/organization/external_storage/{external_storage_id}/validate", "Validateanexternalstorageconfiguration", "admin", "", "", "", "", "ExternalStorageResponse", ""},
{Call::kSpendLimitGet, "spend_limit.get", "GET", "/organization/spend_limit", "Getorganizationspendlimit", "admin", "", "", "", "", "OrganizationSpendLimitResource", ""},
{Call::kSpendLimitUpdate, "spend_limit.update", "POST", "/organization/spend_limit", "Updateorganizationspendlimit", "admin", "threshold_amount,currency,interval", "threshold_amount,currency,interval", "", "UpdateOrganizationSpendLimitBody", "OrganizationSpendLimitResource", ""},
{Call::kSpendLimitDelete, "spend_limit.delete", "DELETE", "/organization/spend_limit", "Deleteorganizationspendlimit", "admin", "", "", "", "", "OrganizationSpendLimitDeletedResource", "destructive"},
{Call::kProjectsSpendLimitGet, "projects.spend_limit.get", "GET", "/organization/projects/{project_id}/spend_limit", "Getprojectspendlimit", "admin", "", "", "", "", "ProjectSpendLimitResource", ""},
{Call::kProjectsSpendLimitUpdate, "projects.spend_limit.update", "POST", "/organization/projects/{project_id}/spend_limit", "Updateprojectspendlimit", "admin", "threshold_amount,currency,interval", "threshold_amount,currency,interval", "", "UpdateProjectSpendLimitBody", "ProjectSpendLimitResource", ""},
{Call::kProjectsSpendLimitDelete, "projects.spend_limit.delete", "DELETE", "/organization/projects/{project_id}/spend_limit", "Deleteprojectspendlimit", "admin", "", "", "", "", "ProjectSpendLimitDeletedResource", "destructive"},
{Call::kProjectsServiceAccountsApiKeysCreate, "projects.service_accounts.api_keys.create", "POST", "/organization/projects/{project_id}/service_accounts/{service_account_id}/api_keys", "CreateanAPIkeyforaserviceaccount", "admin", "name,scopes,expires_in_seconds", "", "", "CreateProjectServiceAccountApiKeyBody", "ServiceAccountApiKeyBody", ""},
{Call::kWebhookEndpointsList, "webhook_endpoints.list", "GET", "/webhook_endpoints", "ListWebhookEndpoints", "project", "", "", "limit,after", "", "WebhookEndpointListResource", ""},
{Call::kWebhookEndpointsCreate, "webhook_endpoints.create", "POST", "/webhook_endpoints", "CreateWebhookEndpoint", "project", "name,url,event_types", "name,url,event_types", "", "PublicCreateEndpointBody", "WebhookEndpointWithSecretResource", ""},
{Call::kWebhookEndpointsGet, "webhook_endpoints.get", "GET", "/webhook_endpoints/{webhook_endpoint_id}", "RetrieveWebhookEndpoint", "project", "", "", "", "", "WebhookEndpointBody", ""},
{Call::kWebhookEndpointsUpdate, "webhook_endpoints.update", "POST", "/webhook_endpoints/{webhook_endpoint_id}", "UpdateWebhookEndpoint", "project", "name,url,event_types", "", "", "PublicUpdateEndpointBody", "WebhookEndpointBody", ""},
{Call::kWebhookEndpointsDelete, "webhook_endpoints.delete", "DELETE", "/webhook_endpoints/{webhook_endpoint_id}", "DeleteWebhookEndpoint", "project", "", "", "", "", "DeletedWebhookEndpointResource", "destructive"},
{Call::kWebhookEndpointsRotateSecret, "webhook_endpoints.rotate_secret", "POST", "/webhook_endpoints/{webhook_endpoint_id}/rotate_secret", "RotateWebhookEndpointSigningSecret", "project", "keep_old_secret_active_for_24_hours", "", "", "PublicRotateSecretBody", "WebhookEndpointWithSecretResource", "destructive"},
{Call::kWebhookEndpointsTest, "webhook_endpoints.test", "POST", "/webhook_endpoints/{webhook_endpoint_id}/test", "TestWebhookEndpoint", "project", "event_type", "event_type", "", "PublicTestEndpointBody", "WebhookEndpointTestResultResource", ""},
{Call::kWebhookEventTypesList, "webhook_event_types.list", "GET", "/webhook_event_types", "ListWebhookEventTypes", "project", "", "", "", "", "WebhookEventTypeListResource", ""},
};
// CALLS-END
// SCHEMAS-BEGIN (response fields we read; checked by tools/check_spec.py)
static const SchemaFields kSchemas[] = {
{"ApiKeyList", "object,data,has_more,first_id,last_id"},
{"AdminApiKeyCreateResponse", "object,id,name,redacted_value,created_at,expires_at,last_used_at,owner,value"},
{"AdminApiKey", "object,id,name,redacted_value,created_at,expires_at,last_used_at,owner"},
{"ListAuditLogsResponse", "object,data,first_id,last_id,has_more"},
{"ListCertificatesResponse", "data,first_id,last_id,has_more,object"},
{"Certificate", "object,id,name,created_at,certificate_details,active"},
{"OrganizationCertificateActivationResponse", "object,data"},
{"OrganizationCertificateDeactivationResponse", "object,data"},
{"DeleteCertificateResponse", "object,id"},
{"UsageResponse", "object,data,has_more,next_page"},
{"OrganizationDataRetention", "object,type"},
{"GroupListResource", "object,data,has_more,next"},
{"GroupResponse", "id,name,created_at,is_scim_managed,group_type"},
{"GroupResourceWithSuccess", "id,name,created_at,is_scim_managed"},
{"GroupDeletedResource", "object,id,deleted"},
{"RoleListResource", "object,data,has_more,next"},
{"GroupRoleAssignment", "object,group,role"},
{"AssignedRoleDetails", "id,name,permissions,resource_type,predefined_role,description,created_at,updated_at,created_by,created_by_user_obj,metadata,assignment_sources"},
{"DeletedRoleAssignmentResource", "object,deleted"},
{"UserListResource", "object,data,has_more,next"},
{"GroupUserAssignment", "object,user_id,group_id"},
{"GroupMemberUser", "id,name,email,picture,is_service_account,user_type"},
{"GroupUserDeletedResource", "object,deleted"},
{"InviteListResponse", "object,data,first_id,last_id,has_more"},
{"Invite", "object,id,email,role,status,created_at,expires_at,accepted_at,projects"},
{"InviteDeleteResponse", "object,id,deleted"},
{"ProjectListResponse", "object,data,first_id,last_id,has_more"},
{"Project", "id,object,name,created_at,archived_at,status,external_key_id,residency"},
{"ProjectApiKeyListResponse", "object,data,first_id,last_id,has_more"},
{"ProjectApiKey", "object,redacted_value,name,created_at,expires_at,last_used_at,id,owner_project_access,owner"},
{"ProjectApiKeyDeleteResponse", "object,id,deleted"},
{"ListProjectCertificatesResponse", "data,first_id,last_id,has_more,object"},
{"OrganizationProjectCertificateActivationResponse", "object,data"},
{"OrganizationProjectCertificateDeactivationResponse", "object,data"},
{"ProjectDataRetention", "object,type"},
{"ProjectGroupListResource", "object,data,has_more,next"},
{"ProjectGroup", "object,project_id,group_id,group_name,group_type,created_at"},
{"ProjectGroupDeletedResource", "object,deleted"},
{"ProjectHostedToolPermissions", "file_search,web_search,image_generation,mcp,code_interpreter"},
{"ProjectModelPermissions", "object,mode,model_ids"},
{"ProjectModelPermissionsDeleteResponse", "object,deleted"},
{"ProjectRateLimitListResponse", "object,data,first_id,last_id,has_more"},
{"ProjectRateLimit", "object,id,model,max_requests_per_1_minute,max_tokens_per_1_minute,max_images_per_1_minute,max_audio_megabytes_per_1_minute,max_requests_per_1_day,batch_1_day_max_input_tokens"},
{"ProjectServiceAccountListResponse", "object,data,first_id,last_id,has_more"},
{"ProjectServiceAccountCreateResponse", "object,id,name,role,created_at,api_key"},
{"ProjectServiceAccount", "object,id,name,role,created_at"},
{"ProjectServiceAccountDeleteResponse", "object,id,deleted"},
{"ProjectSpendAlertListResource", "object,data,first_id,last_id,has_more"},
{"ProjectSpendAlert", "id,object,threshold_amount,currency,interval,notification_channel"},
{"ProjectSpendAlertDeletedResource", "id,object,deleted"},
{"ProjectUserListResponse", "object,data,first_id,last_id,has_more"},
{"ProjectUser", "object,id,name,email,role,added_at"},
{"ProjectUserDeleteResponse", "object,id,deleted"},
{"PublicRoleListResource", "object,data,has_more,next"},
{"Role", "object,id,name,description,permissions,resource_type,predefined_role"},
{"RoleDeletedResource", "object,id,deleted"},
{"OrganizationSpendAlertListResource", "object,data,first_id,last_id,has_more"},
{"OrganizationSpendAlert", "id,object,threshold_amount,currency,interval,notification_channel"},
{"OrganizationSpendAlertDeletedResource", "id,object,deleted"},
{"UserListResponse", "object,data,first_id,last_id,has_more"},
{"User", "object,id,name,email,role,added_at,is_default,created,user,is_service_account,is_scale_tier_authorized_purchaser,is_scim_managed,api_key_last_used_at,technical_level,developer_persona,projects"},
{"UserDeleteResponse", "object,id,deleted"},
{"UserRoleAssignment", "object,user,role"},
{"PublicDecisionsUsageResponseResource", "object,has_more,next_page,data"},
{"ExternalStorageListResource", "object,data,first_id,last_id,has_more"},
{"ExternalStorageResponse", "object,id,project_id,provider,geography,status,created_at"},
{"ExternalStorageDeletedResource", "object,id,deleted"},
{"OrganizationSpendLimitResource", "object,threshold_amount,currency,interval,enforcement"},
{"OrganizationSpendLimitDeletedResource", "object,deleted"},
{"ProjectSpendLimitResource", "object,threshold_amount,currency,interval,enforcement"},
{"ProjectSpendLimitDeletedResource", "object,deleted"},
{"ServiceAccountApiKeyBody", "object,value,name,created_at,expires_at,id"},
{"WebhookEndpointListResource", "object,data,first_id,last_id,has_more"},
{"WebhookEndpointWithSecretResource", "id,object,created_at,updated_at,name,url,event_types,signing_secret_hint,signing_secret"},
{"WebhookEndpointBody", "id,object,created_at,updated_at,name,url,event_types,signing_secret_hint"},
{"DeletedWebhookEndpointResource", "id,object,deleted"},
{"WebhookEndpointTestResultResource", "object,webhook_endpoint_id,event_type,status_code,success"},
{"WebhookEventTypeListResource", "object,data"},
{"AuditLog", "id,type,effective_at,project,actor,api_key.created,api_key.updated,api_key.deleted,checkpoint.permission.created,checkpoint.permission.deleted,external_key.registered,external_key.removed,external_storage.registered,external_storage.removed,group.created,group.updated,group.deleted,scim.enabled,scim.disabled,invite.sent,invite.accepted,invite.deleted,ip_allowlist.created,ip_allowlist.updated,ip_allowlist.deleted,ip_allowlist.config.activated,ip_allowlist.config.deactivated,login.succeeded,login.failed,logout.succeeded,logout.failed,organization.updated,project.created,project.updated,project.archived,project.deleted,rate_limit.updated,rate_limit.deleted,role.created,role.updated,role.deleted,role.assignment.created,role.assignment.deleted,role.bound_to_resource,role.unbound_from_resource,service_account.created,service_account.updated,service_account.deleted,workload_identity_provider.created,workload_identity_provider.updated,workload_identity_provider.deleted,workload_identity_provider_mapping.created,workload_identity_provider_mapping.updated,workload_identity_provider_mapping.deleted,user.added,user.updated,user.deleted,certificate.created,certificate.updated,certificate.deleted,certificates.activated,certificates.deactivated"},
{"UsageTimeBucket", "object,start_time,end_time,results"},
{"CostsResult", "api_source,object,amount,line_item,project_id,user_id,api_key_id,quantity,quantity_unit"},
{"UsageCompletionsResult", "api_source,object,input_tokens,input_cached_tokens,input_cache_write_tokens,input_cache_write_30m_tokens,input_cache_write_12h_tokens,input_uncached_tokens,output_tokens,input_text_tokens,output_text_tokens,input_cached_text_tokens,input_audio_tokens,input_cached_audio_tokens,output_audio_tokens,input_image_tokens,input_cached_image_tokens,output_image_tokens,num_model_requests,project_id,user_id,api_key_id,model,batch,service_tier"},
{"UsageEmbeddingsResult", "object,input_tokens,num_model_requests,project_id,user_id,api_key_id,model"},
{"UsageModerationsResult", "object,input_tokens,num_model_requests,project_id,user_id,api_key_id,model"},
{"UsageImagesResult", "object,images,num_model_requests,source,size,project_id,user_id,api_key_id,model"},
{"UsageAudioSpeechesResult", "object,characters,num_model_requests,project_id,user_id,api_key_id,model"},
{"UsageAudioTranscriptionsResult", "object,seconds,num_model_requests,project_id,user_id,api_key_id,model"},
{"UsageVectorStoresResult", "object,usage_bytes,project_id"},
{"UsageCodeInterpreterSessionsResult", "object,num_sessions,project_id"},
{"UsageFileSearchCallsResult", "object,num_requests,project_id,user_id,api_key_id,vector_store_id"},
{"UsageWebSearchCallsResult", "api_source,object,num_model_requests,num_requests,project_id,user_id,api_key_id,model,context_level"},
};
// SCHEMAS-END
std::size_t CallTable::size() { return sizeof(kCalls) / sizeof(kCalls[0]); }
const CallSpec& CallTable::at(std::size_t index) {
if (index >= size()) throw llm::ApiError::invalid(kVendor, "call index out of range");
return kCalls[index];
}
const CallSpec& CallTable::spec(Call call) {
const auto index = static_cast<std::size_t>(call);
if (index >= size() || kCalls[index].call != call)
throw llm::ApiError::invalid(kVendor, "call table out of order");
return kCalls[index];
}
const CallSpec* CallTable::find(const std::string& key) {
for (const CallSpec& row : kCalls)
if (key == row.key) return &row;
return nullptr;
}
clients::Method CallTable::method(Call call) {
const char* m = spec(call).http_method;
if (std::strcmp(m, "GET") == 0) return clients::Method::kGet;
if (std::strcmp(m, "POST") == 0) return clients::Method::kPost;
if (std::strcmp(m, "DELETE") == 0) return clients::Method::kDelete;
throw llm::ApiError::invalid(kVendor, "unsupported method in call table");
}
AuthKind CallTable::auth(Call call) {
return std::strcmp(spec(call).auth, "project") == 0 ? AuthKind::kProject : AuthKind::kAdmin;
}
bool CallTable::destructive(Call call) {
return std::strcmp(spec(call).flags, "destructive") == 0;
}
std::vector<std::string> CallTable::split(const char* list) {
std::vector<std::string> out;
std::string cur;
for (const char* p = list; *p; ++p) {
if (*p == ',') {
if (!cur.empty()) out.push_back(cur);
cur.clear();
} else {
cur += *p;
}
}
if (!cur.empty()) out.push_back(cur);
return out;
}
std::vector<std::string> CallTable::path_params(Call call) {
std::vector<std::string> out;
const std::string path = spec(call).path;
std::size_t at = 0;
while ((at = path.find('{', at)) != std::string::npos) {
const std::size_t end = path.find('}', at);
if (end == std::string::npos) break;
out.push_back(path.substr(at + 1, end - at - 1));
at = end + 1;
}
return out;
}
std::string CallTable::render(Call call, const std::vector<std::string>& ids) {
const std::vector<std::string> names = path_params(call);
if (ids.size() != names.size())
throw llm::ApiError::invalid(kVendor, std::string(spec(call).key) + " takes " +
std::to_string(names.size()) + " id(s)");
std::string path = spec(call).path;
for (std::size_t i = 0; i < names.size(); ++i) {
if (!llm::Service::valid_id(ids[i]))
throw llm::ApiError::invalid(kVendor, "bad " + names[i]);
const std::string token = "{" + names[i] + "}";
path.replace(path.find(token), token.size(), ids[i]);
}
return path;
}
bool CallTable::allows_body_field(Call call, const std::string& field) {
for (const std::string& f : split(spec(call).body_fields))
if (f == field) return true;
return false;
}
std::vector<std::string> CallTable::required_body_fields(Call call) {
return split(spec(call).required_fields);
}
bool CallTable::allows_query(Call call, const std::string& name) {
for (const std::string& q : split(spec(call).query_params))
if (q == name) return true;
// Object parameters are sent as name[key] (effective_at[gte]=...).
static const char* const kObjectParams[] = {"effective_at"};
for (const char* base : kObjectParams) {
const std::string prefix = std::string(base) + "[";
if (name.rfind(prefix, 0) == 0 && name.back() == ']')
for (const std::string& q : split(spec(call).query_params))
if (q == base) return true;
}
return false;
}
std::size_t CallTable::schema_count() { return sizeof(kSchemas) / sizeof(kSchemas[0]); }
const SchemaFields& CallTable::schema_at(std::size_t index) {
if (index >= schema_count()) throw llm::ApiError::invalid(kVendor, "schema index out of range");
return kSchemas[index];
}
const SchemaFields* CallTable::schema(const std::string& name) {
for (const SchemaFields& s : kSchemas)
if (name == s.schema) return &s;
return nullptr;
}
} // namespace molo::openai::admin
+101
View File
@@ -0,0 +1,101 @@
#pragma once
// The ONE table of REST calls this package makes. Every row is checked against
// OpenAI's published OpenAPI document by tools/check_spec.py. Code builds every
// URL from this table, never from a literal.
#include <cstddef>
#include <string>
#include <vector>
#include "clients/request.h"
namespace molo::openai::admin {
enum class Call {
kAdminApiKeysList, kAdminApiKeysCreate, kAdminApiKeysGet, kAdminApiKeysDelete, kAuditLogsList,
kCertificatesList, kCertificatesCreate, kCertificatesActivate, kCertificatesDeactivate,
kCertificatesGet, kCertificatesUpdate, kCertificatesDelete, kCosts, kDataRetentionGet,
kDataRetentionUpdate, kGroupsList, kGroupsCreate, kGroupsGet, kGroupsUpdate, kGroupsDelete,
kGroupsRolesList, kGroupsRolesCreate, kGroupsRolesGet, kGroupsRolesDelete, kGroupsUsersList,
kGroupsUsersCreate, kGroupsUsersGet, kGroupsUsersDelete, kInvitesList, kInvitesCreate,
kInvitesGet, kInvitesDelete, kProjectsList, kProjectsCreate, kProjectsGet, kProjectsUpdate,
kProjectsApiKeysList, kProjectsApiKeysGet, kProjectsApiKeysUpdate, kProjectsApiKeysDelete,
kProjectsArchive, kProjectsCertificatesList, kProjectsCertificatesActivate,
kProjectsCertificatesDeactivate, kProjectsDataRetentionGet, kProjectsDataRetentionUpdate,
kProjectsGroupsList, kProjectsGroupsCreate, kProjectsGroupsGet, kProjectsGroupsDelete,
kProjectsHostedToolPermissionsGet, kProjectsHostedToolPermissionsUpdate,
kProjectsModelPermissionsGet, kProjectsModelPermissionsUpdate, kProjectsModelPermissionsDelete,
kProjectsRateLimitsList, kProjectsRateLimitsUpdate, kProjectsServiceAccountsList,
kProjectsServiceAccountsCreate, kProjectsServiceAccountsGet, kProjectsServiceAccountsUpdate,
kProjectsServiceAccountsDelete, kProjectsSpendAlertsList, kProjectsSpendAlertsCreate,
kProjectsSpendAlertsGet, kProjectsSpendAlertsUpdate, kProjectsSpendAlertsDelete,
kProjectsUsersList, kProjectsUsersCreate, kProjectsUsersGet, kProjectsUsersUpdate,
kProjectsUsersDelete, kRolesList, kRolesCreate, kRolesGet, kRolesUpdate, kRolesDelete,
kSpendAlertsList, kSpendAlertsCreate, kSpendAlertsGet, kSpendAlertsUpdate, kSpendAlertsDelete,
kUsageAudioSpeeches, kUsageAudioTranscriptions, kUsageCodeInterpreterSessions,
kUsageCompletions, kUsageEmbeddings, kUsageFileSearchCalls, kUsageImages, kUsageModerations,
kUsageVectorStores, kUsageWebSearchCalls, kUsersList, kUsersGet, kUsersUpdate, kUsersDelete,
kUsersRolesList, kUsersRolesCreate, kUsersRolesGet, kUsersRolesDelete, kUsageDecisions,
kExternalStorageList, kExternalStorageCreate, kExternalStorageGet, kExternalStorageDelete,
kExternalStorageValidate, kSpendLimitGet, kSpendLimitUpdate, kSpendLimitDelete,
kProjectsSpendLimitGet, kProjectsSpendLimitUpdate, kProjectsSpendLimitDelete,
kProjectsServiceAccountsApiKeysCreate, kWebhookEndpointsList, kWebhookEndpointsCreate,
kWebhookEndpointsGet, kWebhookEndpointsUpdate, kWebhookEndpointsDelete,
kWebhookEndpointsRotateSecret, kWebhookEndpointsTest, kWebhookEventTypesList,
};
// Which credential a call needs. The organization surface takes an admin key
// only; the webhook endpoint management calls take a project API key
// (OpenAPI security: default ApiKeyAuth, see SPEC.md).
enum class AuthKind { kAdmin, kProject };
struct CallSpec {
Call call;
const char* key; // stable name, "projects.users.list"
const char* http_method; // GET POST DELETE
const char* path; // OpenAPI path under /v1, "{id}" placeholders
const char* op_id; // OpenAPI operationId
const char* auth; // "admin" or "project"
const char* body_fields; // comma list: request body fields we may send
const char* required_fields; // comma list: body fields that must be present
const char* query_params; // comma list: query parameter names (literal, with [])
const char* request_schema; // named request schema, "" when inline
const char* response_schema; // named 200 response schema, "" when inline
const char* flags; // "destructive" or ""
};
struct SchemaFields {
const char* schema; // components.schemas name
const char* fields; // comma list: properties we read
};
class CallTable {
public:
static std::size_t size();
static const CallSpec& at(std::size_t index);
static const CallSpec& spec(Call call);
static const CallSpec* find(const std::string& key);
static clients::Method method(Call call);
static AuthKind auth(Call call);
static bool destructive(Call call);
// Ordered {placeholder} names of the path template ("project_id", "user_id").
static std::vector<std::string> path_params(Call call);
// Replaces the placeholders in order. Every id is validated (one URL path
// segment of [A-Za-z0-9._:-], 1..256, not "." or ".."); the count must match.
static std::string render(Call call, const std::vector<std::string>& ids);
static bool allows_body_field(Call call, const std::string& field);
static std::vector<std::string> required_body_fields(Call call);
static bool allows_query(Call call, const std::string& name);
static std::size_t schema_count();
static const SchemaFields& schema_at(std::size_t index);
static const SchemaFields* schema(const std::string& name);
// Comma-list helpers shared with the audit and usage code.
static std::vector<std::string> split(const char* comma_list);
};
} // namespace molo::openai::admin
+62
View File
@@ -0,0 +1,62 @@
#pragma once
// Static ceilings for the OpenAI organization administration surface. Never
// autotuned. Values marked (api) are ranges OpenAI documents; the rest are
// local floors and ceilings chosen here and listed in SPEC.md section 3.
#include <cstddef>
#include <cstdint>
namespace molo::openai::admin {
struct AdminCaps {
// Paging.
static constexpr int kDefaultPageLimit = 20; // (api) default of every list
static constexpr int kMaxPageLimit = 100; // (api) 1..100 on id-cursor lists
static constexpr int kMaxListPages = 20; // page walks stop here, loudly
static constexpr std::size_t kMaxWalkItems = 2000; // items returned by one walk
static constexpr std::size_t kMaxCursorChars = 512; // after / before / page tokens
// Usage and costs: bucket limits per bucket_width (api: the parameter text).
static constexpr int kMaxBuckets1d = 31;
static constexpr int kMaxBuckets1h = 168;
static constexpr int kMaxBuckets1m = 1440;
static constexpr int kDefaultBuckets1d = 7;
static constexpr int kMaxCostBuckets = 180; // (api) costs: 1..180, default 7
static constexpr std::size_t kMaxFilterValues = 100; // values in one array filter
static constexpr std::size_t kMaxFilterChars = 256; // chars in one filter value
static constexpr std::size_t kMaxGroupBy = 8;
static constexpr std::int64_t kMaxTimeSeconds = 4102444800; // 2100-01-01
// Names and free text.
static constexpr std::size_t kMaxNameChars = 256;
static constexpr std::size_t kMaxEmailChars = 320;
static constexpr std::size_t kMaxDescriptionChars = 1024;
static constexpr std::size_t kMaxRoleChars = 128;
static constexpr std::size_t kMaxPermissions = 256;
static constexpr std::size_t kMaxInviteProjects = 100;
static constexpr std::size_t kMaxModelIds = 500;
static constexpr std::size_t kMaxScopes = 32;
static constexpr std::int64_t kMaxExpiresInSeconds = 315360000; // 10 years
static constexpr std::size_t kMaxCertificateIds = 10;
static constexpr std::size_t kMaxCertificatePemBytes = 64u * 1024u;
// Audit logs.
static constexpr std::size_t kMaxAuditEventTypes = 50;
// Webhooks.
static constexpr std::size_t kMaxWebhookBodyBytes = 1024u * 1024u;
static constexpr std::size_t kMaxWebhookHeaderChars = 4096;
static constexpr std::size_t kMaxWebhookSignatures = 8;
static constexpr std::int64_t kDefaultToleranceSeconds = 300; // SDK default: 5 minutes
static constexpr std::int64_t kMaxToleranceSeconds = 3600;
static constexpr std::size_t kMinSecretBytes = 24; // SDK: decoded whsec_ key
static constexpr std::size_t kMaxSecretChars = 512;
static constexpr std::size_t kMaxWebhookUrlChars = 2048;
static constexpr std::size_t kMaxEndpointEventTypes = 64;
// Request body ceiling for a single admin call (all bodies are small).
static constexpr std::size_t kMaxBodyBytes = 256u * 1024u;
};
} // namespace molo::openai::admin
+9
View File
@@ -0,0 +1,9 @@
// Link shim. src/ai.mk (shared, not editable from this package) compiles only
// src/security/crypto/Base64.cpp into libai, but WebhookVerifier uses
// security::crypto::Hmac (and SecureRandom::constant_time_equal), which need
// Sha256.cpp, Hmac.cpp and SecureRandom.cpp. They are compiled here until the
// integration step adds those three files to AI_SRCS in src/ai.mk; then delete
// this file (keeping both would be a duplicate symbol error at link time).
#include "security/crypto/Sha256.cpp"
#include "security/crypto/Hmac.cpp"
#include "security/crypto/SecureRandom.cpp"
+160
View File
@@ -0,0 +1,160 @@
#include "openai/admin/governance.h"
#include "openai/admin/caps.h"
#include "openai/admin/validate.h"
namespace molo::openai::admin {
using J = AdminService::Json;
// ---- certificates ----
void Certificates::require_org(const char* what) const {
if (!project_id_.empty())
Validate::fail(std::string(what) + " exists at organization scope only");
}
J Certificates::list(const ListOptions& options) {
if (project_id_.empty()) return execute(Call::kCertificatesList, {}, options.to_query());
return execute(Call::kProjectsCertificatesList, {project_id_}, options.to_query());
}
J Certificates::get(const std::string& certificate_id, bool include_content) {
require_org("get certificate");
Query q;
if (include_content) q.set("include", "content");
return execute(Call::kCertificatesGet, {certificate_id}, q);
}
J Certificates::upload(const CertificateUpload& certificate) {
require_org("upload certificate");
Json body = certificate.to_json();
return execute(Call::kCertificatesCreate, {}, {}, &body);
}
J Certificates::rename(const std::string& certificate_id, const std::string& name) {
require_org("rename certificate");
Validate::text("name", name, AdminCaps::kMaxNameChars);
Json body = object_of({{"name", Json(name)}});
return execute(Call::kCertificatesUpdate, {certificate_id}, {}, &body);
}
J Certificates::destroy(const std::string& certificate_id, bool confirm) {
require_org("delete certificate");
return execute(Call::kCertificatesDelete, {certificate_id}, {}, nullptr, confirm);
}
J Certificates::toggle(Call org_call, Call project_call, const std::vector<std::string>& ids,
bool confirm) {
Validate::count("certificate_ids", ids.size(), AdminCaps::kMaxCertificateIds, false);
Json list = Json::array();
for (const std::string& id : ids) {
Validate::id("certificate id", id);
list.push(Json(id));
}
Json body = Json::object();
body.set("certificate_ids", list);
if (project_id_.empty()) return execute(org_call, {}, {}, &body, confirm);
return execute(project_call, {project_id_}, {}, &body, confirm);
}
J Certificates::activate(const std::vector<std::string>& certificate_ids) {
return toggle(Call::kCertificatesActivate, Call::kProjectsCertificatesActivate, certificate_ids,
false);
}
J Certificates::deactivate(const std::vector<std::string>& certificate_ids, bool confirm) {
return toggle(Call::kCertificatesDeactivate, Call::kProjectsCertificatesDeactivate,
certificate_ids, confirm);
}
// ---- spend alerts ----
std::vector<std::string> SpendAlerts::ids(const std::string& alert_id) const {
std::vector<std::string> out;
if (!project_id_.empty()) out.push_back(project_id_);
if (!alert_id.empty()) out.push_back(alert_id);
return out;
}
J SpendAlerts::list(const ListOptions& options) {
return execute(project_id_.empty() ? Call::kSpendAlertsList : Call::kProjectsSpendAlertsList,
ids(), options.to_query());
}
J SpendAlerts::get(const std::string& alert_id) {
Validate::id("alert_id", alert_id);
return execute(project_id_.empty() ? Call::kSpendAlertsGet : Call::kProjectsSpendAlertsGet,
ids(alert_id));
}
J SpendAlerts::create(const SpendAlertSpec& spec) {
Json body = spec.to_json();
return execute(project_id_.empty() ? Call::kSpendAlertsCreate : Call::kProjectsSpendAlertsCreate,
ids(), {}, &body);
}
J SpendAlerts::update(const std::string& alert_id, const SpendAlertSpec& spec) {
Validate::id("alert_id", alert_id);
Json body = spec.to_json();
return execute(project_id_.empty() ? Call::kSpendAlertsUpdate : Call::kProjectsSpendAlertsUpdate,
ids(alert_id), {}, &body);
}
J SpendAlerts::destroy(const std::string& alert_id, bool confirm) {
Validate::id("alert_id", alert_id);
return execute(project_id_.empty() ? Call::kSpendAlertsDelete : Call::kProjectsSpendAlertsDelete,
ids(alert_id), {}, nullptr, confirm);
}
// ---- organization policy ----
J OrganizationPolicies::spend_limit() { return execute(Call::kSpendLimitGet); }
J OrganizationPolicies::set_spend_limit(const SpendLimitSpec& limit) {
Json body = limit.to_json();
return execute(Call::kSpendLimitUpdate, {}, {}, &body);
}
J OrganizationPolicies::clear_spend_limit(bool confirm) {
return execute(Call::kSpendLimitDelete, {}, {}, nullptr, confirm);
}
J OrganizationPolicies::data_retention() { return execute(Call::kDataRetentionGet); }
J OrganizationPolicies::set_data_retention(const std::string& retention_type, bool confirm) {
Json body = DataRetention::organization(retention_type);
return execute(Call::kDataRetentionUpdate, {}, {}, &body, confirm);
}
// ---- external storage ----
J ExternalStorage::list(const ListOptions& options, const std::string& project_id) {
if (!options.before.empty())
Validate::fail("external storage lists take limit, after and order only");
Query q = options.to_query();
if (!project_id.empty()) {
Validate::id("project_id", project_id);
q.set("project_id", project_id);
}
return execute(Call::kExternalStorageList, {}, q);
}
J ExternalStorage::get(const std::string& external_storage_id) {
return execute(Call::kExternalStorageGet, {external_storage_id});
}
J ExternalStorage::create(const ExternalStorageSpec& spec) {
Json body = spec.to_json();
return execute(Call::kExternalStorageCreate, {}, {}, &body);
}
J ExternalStorage::validate(const std::string& external_storage_id) {
return execute(Call::kExternalStorageValidate, {external_storage_id});
}
J ExternalStorage::destroy(const std::string& external_storage_id, bool confirm) {
return execute(Call::kExternalStorageDelete, {external_storage_id}, {}, nullptr, confirm);
}
} // namespace molo::openai::admin
+79
View File
@@ -0,0 +1,79 @@
#pragma once
// Organization governance: mTLS certificates, spend alerts, spend limit, data
// retention, external storage. Certificates and spend alerts exist at two
// scopes: the organization (default) and one project (pass its id).
#include <string>
#include <vector>
#include "openai/admin/admin_service.h"
#include "openai/admin/requests.h"
namespace molo::openai::admin {
class Certificates : public AdminService {
public:
// project_id empty: organization scope. Upload, get, rename and delete only
// exist at organization scope; calling them on a project scope throws.
explicit Certificates(std::shared_ptr<AdminApiClient> client, std::string project_id = "")
: AdminService(std::move(client)), project_id_(std::move(project_id)) {}
Json list(const ListOptions& options = {});
// include_content adds the PEM body to the answer (query include=content).
Json get(const std::string& certificate_id, bool include_content);
Json upload(const CertificateUpload& certificate);
Json rename(const std::string& certificate_id, const std::string& name);
Json destroy(const std::string& certificate_id, bool confirm);
Json activate(const std::vector<std::string>& certificate_ids);
Json deactivate(const std::vector<std::string>& certificate_ids, bool confirm);
private:
Json toggle(Call org_call, Call project_call, const std::vector<std::string>& ids, bool confirm);
void require_org(const char* what) const;
std::string project_id_;
};
class SpendAlerts : public AdminService {
public:
explicit SpendAlerts(std::shared_ptr<AdminApiClient> client, std::string project_id = "")
: AdminService(std::move(client)), project_id_(std::move(project_id)) {}
Json list(const ListOptions& options = {});
Json get(const std::string& alert_id);
Json create(const SpendAlertSpec& spec);
Json update(const std::string& alert_id, const SpendAlertSpec& spec);
Json destroy(const std::string& alert_id, bool confirm);
private:
std::vector<std::string> ids(const std::string& alert_id = "") const;
std::string project_id_;
};
// Organization-wide policy: hard spend limit, data retention.
class OrganizationPolicies : public AdminService {
public:
explicit OrganizationPolicies(std::shared_ptr<AdminApiClient> client)
: AdminService(std::move(client)) {}
Json spend_limit();
Json set_spend_limit(const SpendLimitSpec& limit);
Json clear_spend_limit(bool confirm);
Json data_retention();
// Changes how OpenAI retains the whole organization's data: needs confirm.
Json set_data_retention(const std::string& retention_type, bool confirm);
};
class ExternalStorage : public AdminService {
public:
explicit ExternalStorage(std::shared_ptr<AdminApiClient> client) : AdminService(std::move(client)) {}
// project_id "" lists all projects.
Json list(const ListOptions& options = {}, const std::string& project_id = "");
Json get(const std::string& external_storage_id);
Json create(const ExternalStorageSpec& spec);
Json validate(const std::string& external_storage_id);
Json destroy(const std::string& external_storage_id, bool confirm);
};
} // namespace molo::openai::admin
+188
View File
@@ -0,0 +1,188 @@
#include "openai/admin/identity.h"
#include "openai/admin/caps.h"
#include "openai/admin/validate.h"
namespace molo::openai::admin {
// ---- admin api keys ----
AdminService::Json AdminApiKeys::list(const ListOptions& options) {
return execute(Call::kAdminApiKeysList, {}, options.to_query());
}
AdminService::Json AdminApiKeys::get(const std::string& key_id) {
return execute(Call::kAdminApiKeysGet, {key_id});
}
AdminService::Json AdminApiKeys::create(const std::string& name,
std::optional<std::int64_t> expires_in_seconds) {
Validate::text("name", name, AdminCaps::kMaxNameChars);
Json body = Json::object();
body.set("name", Json(name));
if (expires_in_seconds) {
Validate::range("expires_in_seconds", *expires_in_seconds, 1, kMaxKeyExpirySeconds);
body.set("expires_in_seconds", Json(static_cast<long>(*expires_in_seconds)));
}
return execute(Call::kAdminApiKeysCreate, {}, {}, &body);
}
AdminService::Json AdminApiKeys::destroy(const std::string& key_id, bool confirm) {
return execute(Call::kAdminApiKeysDelete, {key_id}, {}, nullptr, confirm);
}
// ---- users ----
AdminService::Json Users::list(const ListOptions& options, const std::vector<std::string>& emails) {
Query q = options.to_query();
for (const std::string& e : emails) Validate::email(e);
q.add_all("emails", emails);
return execute(Call::kUsersList, {}, q);
}
AdminService::Json Users::get(const std::string& user_id) {
return execute(Call::kUsersGet, {user_id});
}
AdminService::Json Users::update(const std::string& user_id, const UserUpdate& update) {
Json body = update.to_json();
return execute(Call::kUsersUpdate, {user_id}, {}, &body);
}
AdminService::Json Users::destroy(const std::string& user_id, bool confirm) {
return execute(Call::kUsersDelete, {user_id}, {}, nullptr, confirm);
}
AdminService::Json Users::list_roles(const std::string& user_id, const ListOptions& options) {
return execute(Call::kUsersRolesList, {user_id}, options.to_query());
}
AdminService::Json Users::assign_role(const std::string& user_id, const std::string& role_id) {
Validate::id("role_id", role_id);
Json body = object_of({{"role_id", Json(role_id)}});
return execute(Call::kUsersRolesCreate, {user_id}, {}, &body);
}
AdminService::Json Users::get_role(const std::string& user_id, const std::string& role_id) {
return execute(Call::kUsersRolesGet, {user_id, role_id});
}
AdminService::Json Users::unassign_role(const std::string& user_id, const std::string& role_id,
bool confirm) {
return execute(Call::kUsersRolesDelete, {user_id, role_id}, {}, nullptr, confirm);
}
// ---- invites ----
AdminService::Json Invites::list(const ListOptions& options) {
Query q;
if (options.limit) {
Validate::range("limit", *options.limit, 1, AdminCaps::kMaxPageLimit);
q.set_int("limit", *options.limit);
}
if (!options.after.empty()) q.set("after", options.after);
return execute(Call::kInvitesList, {}, q);
}
AdminService::Json Invites::get(const std::string& invite_id) {
return execute(Call::kInvitesGet, {invite_id});
}
AdminService::Json Invites::create(const InviteRequest& request) {
Json body = request.to_json();
return execute(Call::kInvitesCreate, {}, {}, &body);
}
AdminService::Json Invites::destroy(const std::string& invite_id, bool confirm) {
return execute(Call::kInvitesDelete, {invite_id}, {}, nullptr, confirm);
}
// ---- groups ----
AdminService::Json Groups::list(const ListOptions& options) {
return execute(Call::kGroupsList, {}, options.to_query());
}
AdminService::Json Groups::get(const std::string& group_id) {
return execute(Call::kGroupsGet, {group_id});
}
AdminService::Json Groups::create(const std::string& name) {
Validate::text("name", name, AdminCaps::kMaxNameChars);
Json body = object_of({{"name", Json(name)}});
return execute(Call::kGroupsCreate, {}, {}, &body);
}
AdminService::Json Groups::rename(const std::string& group_id, const std::string& name) {
Validate::text("name", name, AdminCaps::kMaxNameChars);
Json body = object_of({{"name", Json(name)}});
return execute(Call::kGroupsUpdate, {group_id}, {}, &body);
}
AdminService::Json Groups::destroy(const std::string& group_id, bool confirm) {
return execute(Call::kGroupsDelete, {group_id}, {}, nullptr, confirm);
}
AdminService::Json Groups::list_users(const std::string& group_id, const ListOptions& options) {
return execute(Call::kGroupsUsersList, {group_id}, options.to_query());
}
AdminService::Json Groups::add_user(const std::string& group_id, const std::string& user_id) {
Validate::id("user_id", user_id);
Json body = object_of({{"user_id", Json(user_id)}});
return execute(Call::kGroupsUsersCreate, {group_id}, {}, &body);
}
AdminService::Json Groups::get_user(const std::string& group_id, const std::string& user_id) {
return execute(Call::kGroupsUsersGet, {group_id, user_id});
}
AdminService::Json Groups::remove_user(const std::string& group_id, const std::string& user_id,
bool confirm) {
return execute(Call::kGroupsUsersDelete, {group_id, user_id}, {}, nullptr, confirm);
}
AdminService::Json Groups::list_roles(const std::string& group_id, const ListOptions& options) {
return execute(Call::kGroupsRolesList, {group_id}, options.to_query());
}
AdminService::Json Groups::assign_role(const std::string& group_id, const std::string& role_id) {
Validate::id("role_id", role_id);
Json body = object_of({{"role_id", Json(role_id)}});
return execute(Call::kGroupsRolesCreate, {group_id}, {}, &body);
}
AdminService::Json Groups::get_role(const std::string& group_id, const std::string& role_id) {
return execute(Call::kGroupsRolesGet, {group_id, role_id});
}
AdminService::Json Groups::unassign_role(const std::string& group_id, const std::string& role_id,
bool confirm) {
return execute(Call::kGroupsRolesDelete, {group_id, role_id}, {}, nullptr, confirm);
}
// ---- roles ----
AdminService::Json Roles::list(const ListOptions& options) {
return execute(Call::kRolesList, {}, options.to_query());
}
AdminService::Json Roles::get(const std::string& role_id) {
return execute(Call::kRolesGet, {role_id});
}
AdminService::Json Roles::create(const RoleSpec& spec) {
Json body = spec.to_json();
return execute(Call::kRolesCreate, {}, {}, &body);
}
AdminService::Json Roles::update(const std::string& role_id, const RoleUpdate& update) {
Json body = update.to_json();
return execute(Call::kRolesUpdate, {role_id}, {}, &body);
}
AdminService::Json Roles::destroy(const std::string& role_id, bool confirm) {
return execute(Call::kRolesDelete, {role_id}, {}, nullptr, confirm);
}
} // namespace molo::openai::admin
+82
View File
@@ -0,0 +1,82 @@
#pragma once
// Organization identity: admin API keys, users, invites, groups, custom roles.
// Every destructive method takes `confirm` with no default.
#include <string>
#include <vector>
#include "openai/admin/admin_service.h"
#include "openai/admin/requests.h"
namespace molo::openai::admin {
// /organization/admin_api_keys. `create` returns the secret value once.
class AdminApiKeys : public AdminService {
public:
explicit AdminApiKeys(std::shared_ptr<AdminApiClient> client) : AdminService(std::move(client)) {}
Json list(const ListOptions& options = {});
Json get(const std::string& key_id);
Json create(const std::string& name, std::optional<std::int64_t> expires_in_seconds = std::nullopt);
Json destroy(const std::string& key_id, bool confirm);
};
// /organization/users and the role assignments of a user.
class Users : public AdminService {
public:
explicit Users(std::shared_ptr<AdminApiClient> client) : AdminService(std::move(client)) {}
Json list(const ListOptions& options = {}, const std::vector<std::string>& emails = {});
Json get(const std::string& user_id);
Json update(const std::string& user_id, const UserUpdate& update);
Json destroy(const std::string& user_id, bool confirm);
Json list_roles(const std::string& user_id, const ListOptions& options = {});
Json assign_role(const std::string& user_id, const std::string& role_id);
Json get_role(const std::string& user_id, const std::string& role_id);
Json unassign_role(const std::string& user_id, const std::string& role_id, bool confirm);
};
// /organization/invites. Invites are created, listed, read and deleted; the
// API has no resend or update.
class Invites : public AdminService {
public:
explicit Invites(std::shared_ptr<AdminApiClient> client) : AdminService(std::move(client)) {}
Json list(const ListOptions& options = {});
Json get(const std::string& invite_id);
Json create(const InviteRequest& request);
Json destroy(const std::string& invite_id, bool confirm);
};
// /organization/groups with their users and role assignments.
class Groups : public AdminService {
public:
explicit Groups(std::shared_ptr<AdminApiClient> client) : AdminService(std::move(client)) {}
Json list(const ListOptions& options = {});
Json get(const std::string& group_id);
Json create(const std::string& name);
Json rename(const std::string& group_id, const std::string& name);
Json destroy(const std::string& group_id, bool confirm);
Json list_users(const std::string& group_id, const ListOptions& options = {});
Json add_user(const std::string& group_id, const std::string& user_id);
Json get_user(const std::string& group_id, const std::string& user_id);
Json remove_user(const std::string& group_id, const std::string& user_id, bool confirm);
Json list_roles(const std::string& group_id, const ListOptions& options = {});
Json assign_role(const std::string& group_id, const std::string& role_id);
Json get_role(const std::string& group_id, const std::string& role_id);
Json unassign_role(const std::string& group_id, const std::string& role_id, bool confirm);
};
// /organization/roles: custom roles and their permissions.
class Roles : public AdminService {
public:
explicit Roles(std::shared_ptr<AdminApiClient> client) : AdminService(std::move(client)) {}
Json list(const ListOptions& options = {});
Json get(const std::string& role_id);
Json create(const RoleSpec& spec);
Json update(const std::string& role_id, const RoleUpdate& update);
Json destroy(const std::string& role_id, bool confirm);
};
} // namespace molo::openai::admin
+53
View File
@@ -0,0 +1,53 @@
#include "openai/admin/openai_admin.h"
#include "clients/transports/http_transport.h"
namespace molo::openai::admin {
namespace {
// webhook_endpoints must always hold a client; an empty-key one reports
// not configured on every call.
std::shared_ptr<ProjectApiClient> or_empty(std::shared_ptr<ProjectApiClient> p) {
if (p) return p;
return ProjectApiClient::with_transport(std::make_unique<clients::transports::HttpTransport>(), "");
}
} // namespace
OpenaiAdmin::OpenaiAdmin(std::shared_ptr<AdminApiClient> admin,
std::shared_ptr<ProjectApiClient> project)
: admin_keys(admin),
users(admin),
invites(admin),
groups(admin),
roles(admin),
projects(admin),
project_users(admin),
service_accounts(admin),
project_api_keys(admin),
rate_limits(admin),
project_groups(admin),
project_policies(admin),
organization_policies(admin),
external_storage(admin),
usage(admin),
costs(admin),
audit_logs(admin),
webhook_endpoints(or_empty(project)),
admin_(std::move(admin)),
project_(std::move(project)) {}
OpenaiAdmin OpenaiAdmin::from_env(Region region) {
OpenaiAdmin out(AdminApiClient::from_env(region), ProjectApiClient::from_env(region));
out.region_ = region;
return out;
}
Certificates OpenaiAdmin::certificates(const std::string& project_id) const {
return Certificates(admin_, project_id);
}
SpendAlerts OpenaiAdmin::spend_alerts(const std::string& project_id) const {
return SpendAlerts(admin_, project_id);
}
} // namespace molo::openai::admin
+66
View File
@@ -0,0 +1,66 @@
#pragma once
// The facade of the package: every resource service built on one admin
// client, plus the optional project-key client for webhook endpoints.
// `OpenaiAdmin::from_env` reads OPENAI_ADMIN_KEY (and OPENAI_API_KEY for
// webhook endpoint management) through llm::Config. A key of the wrong kind
// is refused with ApiError 401 WRONG_KEY_KIND.
#include <memory>
#include <optional>
#include <string>
#include "openai/admin/admin_client.h"
#include "openai/admin/audit_log.h"
#include "openai/admin/governance.h"
#include "openai/admin/identity.h"
#include "openai/admin/projects.h"
#include "openai/admin/usage.h"
#include "openai/admin/webhooks.h"
namespace molo::openai::admin {
class OpenaiAdmin {
public:
OpenaiAdmin(std::shared_ptr<AdminApiClient> admin,
std::shared_ptr<ProjectApiClient> project = nullptr);
// Throws ApiError WRONG_KEY_KIND for a mis-typed key; empty keys are fine
// (every call then answers NotConfiguredError before any traffic).
static OpenaiAdmin from_env(Region region = Region::kGlobal);
bool configured() const { return admin_->configured(); }
bool webhook_management_configured() const { return project_ && project_->configured(); }
Region region() const { return region_; }
const llm::ApiClient& client() const { return *admin_; }
AdminApiKeys admin_keys;
Users users;
Invites invites;
Groups groups;
Roles roles;
Projects projects;
ProjectUsers project_users;
ServiceAccounts service_accounts;
ProjectApiKeys project_api_keys;
RateLimits rate_limits;
ProjectGroups project_groups;
ProjectPolicies project_policies;
OrganizationPolicies organization_policies;
ExternalStorage external_storage;
Usage usage;
Costs costs;
AuditLogs audit_logs;
// Null-safe: calls throw NotConfiguredError when no project key is set.
WebhookEndpoints webhook_endpoints;
Certificates certificates(const std::string& project_id = "") const;
SpendAlerts spend_alerts(const std::string& project_id = "") const;
private:
std::shared_ptr<AdminApiClient> admin_;
std::shared_ptr<ProjectApiClient> project_;
Region region_ = Region::kGlobal;
};
} // namespace molo::openai::admin
+80
View File
@@ -0,0 +1,80 @@
#include "openai/admin/page.h"
#include "llm/error.h"
#include "openai/admin/caps.h"
namespace molo::openai::admin {
using clients::body::Json;
namespace {
std::string text_or_empty(const Json& doc, const char* key) {
const Json* v = doc.find(key);
return v && v->is_string() ? v->as_string() : "";
}
} // namespace
Page::Page(Json envelope) : envelope_(std::move(envelope)) {
if (!envelope_.is_object() || !envelope_.find("data") || !envelope_.find("data")->is_array())
throw llm::ApiError("openai", 502, "BAD_RESPONSE", "list response has no data array");
const Json* more = envelope_.find("has_more");
has_more_ = more && more->is_bool() && more->as_bool();
token_style_ = envelope_.find("next_page") != nullptr;
first_id_ = text_or_empty(envelope_, "first_id");
last_id_ = text_or_empty(envelope_, "last_id");
next_page_ = text_or_empty(envelope_, "next_page");
}
const Json::Array& Page::items() const { return envelope_.find("data")->as_array(); }
std::string Page::next_cursor() const {
if (!has_more_) return "";
return token_style_ ? next_page_ : last_id_;
}
Json WalkResult::to_json() const {
Json o = Json::object();
o.set("data", items);
o.set("pages", Json(pages));
o.set("count", Json(static_cast<long>(items.as_array().size())));
o.set("truncated", Json(truncated));
if (truncated) {
o.set("truncated_reason", Json(reason));
o.set("next_cursor", Json(next_cursor));
}
return o;
}
WalkResult PageWalker::walk(const Fetch& fetch, const std::string& start_cursor) {
WalkResult out;
std::string cursor = start_cursor;
for (;;) {
Page page(fetch(cursor));
++out.pages;
for (const Json& item : page.items()) {
if (out.items.as_array().size() >= AdminCaps::kMaxWalkItems) {
out.truncated = true;
out.reason = "item ceiling";
out.next_cursor = cursor;
return out;
}
out.items.push(item);
}
cursor = page.next_cursor();
if (cursor.empty()) {
if (page.has_more()) { // more data but no way to continue: say so
out.truncated = true;
out.reason = "server sent has_more without a cursor";
}
return out;
}
if (out.pages >= AdminCaps::kMaxListPages) {
out.truncated = true;
out.reason = "page ceiling";
out.next_cursor = cursor;
return out;
}
}
}
} // namespace molo::openai::admin
+59
View File
@@ -0,0 +1,59 @@
#pragma once
// List envelopes and bounded page walks.
//
// Two paging styles exist in the API:
// cursor {object:"list", data, first_id, last_id, has_more}, next page is
// `after=<last_id>` (users, projects, groups, audit logs, ...)
// token {object:"page", data, has_more, next_page}, next page is
// `page=<next_page>` (usage and costs)
// A walk never exceeds AdminCaps::kMaxListPages pages or kMaxWalkItems items;
// when it stops with more data available, `truncated` is true and `reason`
// says which ceiling was hit. Truncation is never silent.
#include <functional>
#include <string>
#include "clients/body/json.h"
namespace molo::openai::admin {
class Page {
public:
explicit Page(clients::body::Json envelope);
const clients::body::Json& envelope() const { return envelope_; }
const clients::body::Json::Array& items() const;
bool has_more() const { return has_more_; }
bool token_style() const { return token_style_; }
const std::string& first_id() const { return first_id_; }
const std::string& last_id() const { return last_id_; }
const std::string& next_page() const { return next_page_; }
// The value to send as `after` (cursor) or `page` (token); "" when done.
std::string next_cursor() const;
private:
clients::body::Json envelope_;
bool has_more_ = false;
bool token_style_ = false;
std::string first_id_, last_id_, next_page_;
};
struct WalkResult {
clients::body::Json items = clients::body::Json::array();
int pages = 0;
bool truncated = false;
std::string reason; // "" or "page ceiling" / "item ceiling"
std::string next_cursor; // resume point when truncated
clients::body::Json to_json() const;
};
class PageWalker {
public:
// fetch(cursor) returns one envelope; cursor is "" for the first page.
using Fetch = std::function<clients::body::Json(const std::string& cursor)>;
static WalkResult walk(const Fetch& fetch, const std::string& start_cursor = "");
};
} // namespace molo::openai::admin
+209
View File
@@ -0,0 +1,209 @@
#include "openai/admin/projects.h"
#include "openai/admin/validate.h"
namespace molo::openai::admin {
using J = AdminService::Json;
// ---- projects ----
J Projects::list(const ListOptions& options, bool include_archived) {
Query q = options.to_query();
if (include_archived) q.set_bool("include_archived", true);
return execute(Call::kProjectsList, {}, q);
}
J Projects::get(const std::string& project_id) { return execute(Call::kProjectsGet, {project_id}); }
J Projects::create(const ProjectCreate& project) {
Json body = project.to_json();
return execute(Call::kProjectsCreate, {}, {}, &body);
}
J Projects::update(const std::string& project_id, const ProjectUpdate& update) {
Json body = update.to_json();
return execute(Call::kProjectsUpdate, {project_id}, {}, &body);
}
J Projects::archive(const std::string& project_id, bool confirm) {
return execute(Call::kProjectsArchive, {project_id}, {}, nullptr, confirm);
}
// ---- project users ----
J ProjectUsers::list(const std::string& project_id, const ListOptions& options) {
return execute(Call::kProjectsUsersList, {project_id}, options.to_query());
}
J ProjectUsers::get(const std::string& project_id, const std::string& user_id) {
return execute(Call::kProjectsUsersGet, {project_id, user_id});
}
J ProjectUsers::create(const std::string& project_id, const ProjectUserCreate& user) {
Json body = user.to_json();
return execute(Call::kProjectsUsersCreate, {project_id}, {}, &body);
}
J ProjectUsers::set_role(const std::string& project_id, const std::string& user_id,
const std::string& role) {
Validate::one_of("role", role, {"owner", "member"});
Json body = object_of({{"role", Json(role)}});
return execute(Call::kProjectsUsersUpdate, {project_id, user_id}, {}, &body);
}
J ProjectUsers::destroy(const std::string& project_id, const std::string& user_id, bool confirm) {
return execute(Call::kProjectsUsersDelete, {project_id, user_id}, {}, nullptr, confirm);
}
// ---- service accounts ----
J ServiceAccounts::list(const std::string& project_id, const ListOptions& options) {
return execute(Call::kProjectsServiceAccountsList, {project_id}, options.to_query());
}
J ServiceAccounts::get(const std::string& project_id, const std::string& service_account_id) {
return execute(Call::kProjectsServiceAccountsGet, {project_id, service_account_id});
}
J ServiceAccounts::create(const std::string& project_id, const ServiceAccountCreate& account) {
Json body = account.to_json();
return execute(Call::kProjectsServiceAccountsCreate, {project_id}, {}, &body);
}
J ServiceAccounts::update(const std::string& project_id, const std::string& service_account_id,
const ServiceAccountUpdate& update) {
Json body = update.to_json();
return execute(Call::kProjectsServiceAccountsUpdate, {project_id, service_account_id}, {}, &body);
}
J ServiceAccounts::destroy(const std::string& project_id, const std::string& service_account_id,
bool confirm) {
return execute(Call::kProjectsServiceAccountsDelete, {project_id, service_account_id}, {}, nullptr,
confirm);
}
J ServiceAccounts::create_key(const std::string& project_id, const std::string& service_account_id,
const ServiceAccountKeyCreate& key) {
Json body = key.to_json();
return execute(Call::kProjectsServiceAccountsApiKeysCreate, {project_id, service_account_id}, {},
&body);
}
// ---- project api keys ----
J ProjectApiKeys::list(const std::string& project_id, const ListOptions& options,
const std::string& owner_project_access) {
Query q = options.to_query();
if (!owner_project_access.empty()) {
Validate::one_of("owner_project_access", owner_project_access, {"active", "inactive", "any"});
q.set("owner_project_access", owner_project_access);
}
return execute(Call::kProjectsApiKeysList, {project_id}, q);
}
J ProjectApiKeys::get(const std::string& project_id, const std::string& api_key_id) {
return execute(Call::kProjectsApiKeysGet, {project_id, api_key_id});
}
J ProjectApiKeys::update(const std::string& project_id, const std::string& api_key_id,
const ProjectApiKeyUpdate& update) {
Json body = update.to_json();
return execute(Call::kProjectsApiKeysUpdate, {project_id, api_key_id}, {}, &body);
}
J ProjectApiKeys::destroy(const std::string& project_id, const std::string& api_key_id,
bool confirm) {
return execute(Call::kProjectsApiKeysDelete, {project_id, api_key_id}, {}, nullptr, confirm);
}
// ---- rate limits ----
J RateLimits::list(const std::string& project_id, const ListOptions& options) {
return execute(Call::kProjectsRateLimitsList, {project_id}, options.to_query());
}
J RateLimits::update(const std::string& project_id, const std::string& rate_limit_id,
const RateLimitUpdate& update) {
Json body = update.to_json();
return execute(Call::kProjectsRateLimitsUpdate, {project_id, rate_limit_id}, {}, &body);
}
// ---- project groups ----
J ProjectGroups::list(const std::string& project_id, const ListOptions& options) {
return execute(Call::kProjectsGroupsList, {project_id}, options.to_query());
}
J ProjectGroups::add(const std::string& project_id, const std::string& group_id,
const std::string& role) {
Validate::id("group_id", group_id);
Validate::text("role", role, 128);
Json body = object_of({{"group_id", Json(group_id)}, {"role", Json(role)}});
return execute(Call::kProjectsGroupsCreate, {project_id}, {}, &body);
}
J ProjectGroups::get(const std::string& project_id, const std::string& group_id,
const std::string& group_type) {
Query q;
if (!group_type.empty()) {
Validate::one_of("group_type", group_type, {"group", "tenant_group"});
q.set("group_type", group_type);
}
return execute(Call::kProjectsGroupsGet, {project_id, group_id}, q);
}
J ProjectGroups::remove(const std::string& project_id, const std::string& group_id, bool confirm) {
return execute(Call::kProjectsGroupsDelete, {project_id, group_id}, {}, nullptr, confirm);
}
// ---- project policies ----
J ProjectPolicies::data_retention(const std::string& project_id) {
return execute(Call::kProjectsDataRetentionGet, {project_id});
}
J ProjectPolicies::set_data_retention(const std::string& project_id,
const std::string& retention_type, bool confirm) {
Json body = DataRetention::project(retention_type);
return execute(Call::kProjectsDataRetentionUpdate, {project_id}, {}, &body, confirm);
}
J ProjectPolicies::model_permissions(const std::string& project_id) {
return execute(Call::kProjectsModelPermissionsGet, {project_id});
}
J ProjectPolicies::set_model_permissions(const std::string& project_id,
const ModelPermissions& permissions) {
Json body = permissions.to_json();
return execute(Call::kProjectsModelPermissionsUpdate, {project_id}, {}, &body);
}
J ProjectPolicies::clear_model_permissions(const std::string& project_id, bool confirm) {
return execute(Call::kProjectsModelPermissionsDelete, {project_id}, {}, nullptr, confirm);
}
J ProjectPolicies::hosted_tool_permissions(const std::string& project_id) {
return execute(Call::kProjectsHostedToolPermissionsGet, {project_id});
}
J ProjectPolicies::set_hosted_tool_permissions(const std::string& project_id,
const HostedToolPermissions& permissions) {
Json body = permissions.to_json();
return execute(Call::kProjectsHostedToolPermissionsUpdate, {project_id}, {}, &body);
}
J ProjectPolicies::spend_limit(const std::string& project_id) {
return execute(Call::kProjectsSpendLimitGet, {project_id});
}
J ProjectPolicies::set_spend_limit(const std::string& project_id, const SpendLimitSpec& limit) {
Json body = limit.to_json();
return execute(Call::kProjectsSpendLimitUpdate, {project_id}, {}, &body);
}
J ProjectPolicies::clear_spend_limit(const std::string& project_id, bool confirm) {
return execute(Call::kProjectsSpendLimitDelete, {project_id}, {}, nullptr, confirm);
}
} // namespace molo::openai::admin
+105
View File
@@ -0,0 +1,105 @@
#pragma once
// Projects and everything that hangs off one: users, service accounts, API
// keys, rate limits, groups, data retention, model and hosted tool
// permissions, spend limit. Destructive methods take `confirm`, no default.
#include <string>
#include "openai/admin/admin_service.h"
#include "openai/admin/requests.h"
namespace molo::openai::admin {
class Projects : public AdminService {
public:
explicit Projects(std::shared_ptr<AdminApiClient> client) : AdminService(std::move(client)) {}
Json list(const ListOptions& options = {}, bool include_archived = false);
Json get(const std::string& project_id);
Json create(const ProjectCreate& project);
Json update(const std::string& project_id, const ProjectUpdate& update);
// Archiving a project cannot be undone through the API.
Json archive(const std::string& project_id, bool confirm);
};
class ProjectUsers : public AdminService {
public:
explicit ProjectUsers(std::shared_ptr<AdminApiClient> client) : AdminService(std::move(client)) {}
Json list(const std::string& project_id, const ListOptions& options = {});
Json get(const std::string& project_id, const std::string& user_id);
Json create(const std::string& project_id, const ProjectUserCreate& user);
Json set_role(const std::string& project_id, const std::string& user_id, const std::string& role);
Json destroy(const std::string& project_id, const std::string& user_id, bool confirm);
};
class ServiceAccounts : public AdminService {
public:
explicit ServiceAccounts(std::shared_ptr<AdminApiClient> client) : AdminService(std::move(client)) {}
Json list(const std::string& project_id, const ListOptions& options = {});
Json get(const std::string& project_id, const std::string& service_account_id);
// The response carries the API key value once, unless create_service_account_only.
Json create(const std::string& project_id, const ServiceAccountCreate& account);
Json update(const std::string& project_id, const std::string& service_account_id,
const ServiceAccountUpdate& update);
Json destroy(const std::string& project_id, const std::string& service_account_id, bool confirm);
// Mints a new API key for the service account (value returned once).
Json create_key(const std::string& project_id, const std::string& service_account_id,
const ServiceAccountKeyCreate& key);
};
class ProjectApiKeys : public AdminService {
public:
explicit ProjectApiKeys(std::shared_ptr<AdminApiClient> client) : AdminService(std::move(client)) {}
// owner_project_access: active | inactive | any, or "" for the server default.
Json list(const std::string& project_id, const ListOptions& options = {},
const std::string& owner_project_access = "");
Json get(const std::string& project_id, const std::string& api_key_id);
Json update(const std::string& project_id, const std::string& api_key_id,
const ProjectApiKeyUpdate& update);
Json destroy(const std::string& project_id, const std::string& api_key_id, bool confirm);
};
class RateLimits : public AdminService {
public:
explicit RateLimits(std::shared_ptr<AdminApiClient> client) : AdminService(std::move(client)) {}
Json list(const std::string& project_id, const ListOptions& options = {});
Json update(const std::string& project_id, const std::string& rate_limit_id,
const RateLimitUpdate& update);
};
class ProjectGroups : public AdminService {
public:
explicit ProjectGroups(std::shared_ptr<AdminApiClient> client) : AdminService(std::move(client)) {}
Json list(const std::string& project_id, const ListOptions& options = {});
Json add(const std::string& project_id, const std::string& group_id, const std::string& role);
// group_type: group | tenant_group, or "" for the server default.
Json get(const std::string& project_id, const std::string& group_id,
const std::string& group_type = "");
Json remove(const std::string& project_id, const std::string& group_id, bool confirm);
};
// Per-project policy: data retention, model permissions, hosted tool
// permissions, hard spend limit.
class ProjectPolicies : public AdminService {
public:
explicit ProjectPolicies(std::shared_ptr<AdminApiClient> client) : AdminService(std::move(client)) {}
Json data_retention(const std::string& project_id);
// Changes how OpenAI retains the project's data: needs confirm.
Json set_data_retention(const std::string& project_id, const std::string& retention_type,
bool confirm);
Json model_permissions(const std::string& project_id);
Json set_model_permissions(const std::string& project_id, const ModelPermissions& permissions);
Json clear_model_permissions(const std::string& project_id, bool confirm);
Json hosted_tool_permissions(const std::string& project_id);
Json set_hosted_tool_permissions(const std::string& project_id,
const HostedToolPermissions& permissions);
Json spend_limit(const std::string& project_id);
Json set_spend_limit(const std::string& project_id, const SpendLimitSpec& limit);
Json clear_spend_limit(const std::string& project_id, bool confirm);
};
} // namespace molo::openai::admin
+93
View File
@@ -0,0 +1,93 @@
#include "openai/admin/query.h"
#include "openai/admin/caps.h"
#include "openai/admin/validate.h"
namespace molo::openai::admin {
namespace {
void check_name(const std::string& name) {
if (name.empty() || name.size() > 64) Validate::fail("bad query parameter name");
for (char c : name)
if (!((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') ||
c == '_' || c == '[' || c == ']'))
Validate::fail("bad query parameter name");
}
constexpr std::size_t kMaxPairs = 256;
} // namespace
Query& Query::set(const std::string& name, const std::string& value) {
check_name(name);
Validate::text("query " + name, value, AdminCaps::kMaxCursorChars, true);
if (pairs_.size() >= kMaxPairs) Validate::fail("too many query parameters");
pairs_.emplace_back(name, value);
return *this;
}
Query& Query::set_int(const std::string& name, std::int64_t value) {
return set(name, std::to_string(value));
}
Query& Query::set_bool(const std::string& name, bool value) {
return set(name, value ? "true" : "false");
}
Query& Query::add_all(const std::string& name, const std::vector<std::string>& values) {
Validate::count(name, values.size(), AdminCaps::kMaxFilterValues, true);
for (const std::string& v : values) {
Validate::text(name, v, AdminCaps::kMaxFilterChars);
set(name, v);
}
return *this;
}
bool Query::has(const std::string& name) const {
for (const auto& p : pairs_)
if (p.first == name) return true;
return false;
}
void Query::check_against(Call call) const {
for (const auto& p : pairs_)
if (!CallTable::allows_query(call, p.first))
Validate::fail(std::string(CallTable::spec(call).key) + " has no query parameter " + p.first);
}
std::string Query::escape(const std::string& text) {
static const char* kHex = "0123456789ABCDEF";
std::string out;
for (unsigned char c : text) {
if ((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') || c == '-' ||
c == '_' || c == '.' || c == '~') {
out += static_cast<char>(c);
} else {
out += '%';
out += kHex[c >> 4];
out += kHex[c & 15];
}
}
return out;
}
std::string Query::encoded() const {
std::string out;
for (const auto& p : pairs_) out += (out.empty() ? "?" : "&") + escape(p.first) + "=" + escape(p.second);
return out;
}
Query ListOptions::to_query() const {
Query q;
if (limit) {
Validate::range("limit", *limit, 1, AdminCaps::kMaxPageLimit);
q.set_int("limit", *limit);
}
if (!after.empty()) q.set("after", after);
if (!before.empty()) q.set("before", before);
if (!order.empty()) {
Validate::one_of("order", order, {"asc", "desc"});
q.set("order", order);
}
return q;
}
} // namespace molo::openai::admin
+53
View File
@@ -0,0 +1,53 @@
#pragma once
// Query strings. `Query` is an ordered, validated, percent-encoded parameter
// list; `ListOptions` is the id-cursor paging every list call shares.
// Array filters repeat the name ("project_ids=a&project_ids=b", the form the
// OpenAPI document declares); names that the spec spells with brackets
// ("project_ids[]" on audit logs) are passed with the brackets.
#include <cstdint>
#include <optional>
#include <string>
#include <utility>
#include <vector>
#include "openai/admin/calls.h"
namespace molo::openai::admin {
class Query {
public:
Query& set(const std::string& name, const std::string& value);
Query& set_int(const std::string& name, std::int64_t value);
Query& set_bool(const std::string& name, bool value);
// One "name=value" pair per entry; entries are capped.
Query& add_all(const std::string& name, const std::vector<std::string>& values);
bool empty() const { return pairs_.empty(); }
std::size_t size() const { return pairs_.size(); }
const std::vector<std::pair<std::string, std::string>>& pairs() const { return pairs_; }
bool has(const std::string& name) const;
// Throws unless every name is a query parameter of the call (table).
void check_against(Call call) const;
// "?a=1&b=2" or "" (percent-encoded, deterministic order of insertion).
std::string encoded() const;
static std::string escape(const std::string& text);
private:
std::vector<std::pair<std::string, std::string>> pairs_;
};
// limit / after / before / order of the id-cursor lists. Which of them a call
// takes is decided by the call table; sending one the call lacks throws.
struct ListOptions {
std::optional<int> limit; // 1..100
std::string after;
std::string before;
std::string order; // "asc" or "desc"
Query to_query() const;
};
} // namespace molo::openai::admin
+383
View File
@@ -0,0 +1,383 @@
#include "openai/admin/requests.h"
#include <algorithm>
#include "openai/admin/admin_client.h"
#include "openai/admin/caps.h"
#include "openai/admin/validate.h"
#include "openai/admin/webhook_events.h"
namespace molo::openai::admin {
namespace {
Json string_array(const std::vector<std::string>& values) {
Json a = Json::array();
for (const std::string& v : values) a.push(Json(v));
return a;
}
void put_int(Json& o, const char* key, const std::optional<std::int64_t>& value) {
if (value) o.set(key, Json(static_cast<long>(*value)));
}
void check_expiry(const std::optional<std::int64_t>& seconds) {
if (seconds) Validate::range("expires_in_seconds", *seconds, 1, kMaxKeyExpirySeconds);
}
void check_scopes(const std::vector<std::string>& scopes) {
Validate::count("scopes", scopes.size(), AdminCaps::kMaxScopes, true);
for (const std::string& s : scopes) Validate::text("scope", s, AdminCaps::kMaxRoleChars);
}
void need_one(const Json& o, const char* what) {
if (o.as_object().empty()) Validate::fail(std::string(what) + " needs at least one field");
}
} // namespace
Json InviteRequest::to_json() const {
Validate::email(email);
Validate::one_of("role", role, {"reader", "owner"});
Validate::count("projects", projects.size(), AdminCaps::kMaxInviteProjects, true);
Json o = Json::object();
o.set("email", Json(email));
o.set("role", Json(role));
if (!projects.empty()) {
Json list = Json::array();
for (const ProjectGrant& g : projects) {
Validate::id("project id", g.id);
Validate::one_of("project role", g.role, {"member", "owner"});
Json p = Json::object();
p.set("id", Json(g.id));
p.set("role", Json(g.role));
list.push(p);
}
o.set("projects", list);
}
return o;
}
Json ProjectCreate::to_json() const {
Validate::text("name", name, AdminCaps::kMaxNameChars);
Json o = Json::object();
o.set("name", Json(name));
if (!residency.empty()) {
const auto& all = Regions::residency_values();
if (std::find(all.begin(), all.end(), residency) == all.end())
Validate::fail("residency is not a PublicProjectResidency value");
o.set("residency", Json(residency));
}
if (!geography.empty()) {
Validate::text("geography", geography, 32);
o.set("geography", Json(geography));
}
if (!external_key_id.empty()) {
Validate::id("external_key_id", external_key_id);
o.set("external_key_id", Json(external_key_id));
}
return o;
}
Json ProjectUpdate::to_json() const {
Json o = Json::object();
if (!name.empty()) {
Validate::text("name", name, AdminCaps::kMaxNameChars);
o.set("name", Json(name));
}
if (!external_key_id.empty()) {
Validate::id("external_key_id", external_key_id);
o.set("external_key_id", Json(external_key_id));
}
if (!geography.empty()) {
Validate::text("geography", geography, 32);
o.set("geography", Json(geography));
}
need_one(o, "project update");
return o;
}
Json ProjectUserCreate::to_json() const {
if (user_id.empty() == email.empty()) Validate::fail("give exactly one of user_id and email");
Validate::one_of("role", role, {"owner", "member"});
Json o = Json::object();
if (!user_id.empty()) {
Validate::id("user_id", user_id);
o.set("user_id", Json(user_id));
} else {
Validate::email(email);
o.set("email", Json(email));
}
o.set("role", Json(role));
return o;
}
Json UserUpdate::to_json() const {
Json o = Json::object();
if (!role.empty()) {
Validate::one_of("role", role, {"owner", "reader"});
o.set("role", Json(role));
}
if (!role_id.empty()) {
Validate::id("role_id", role_id);
o.set("role_id", Json(role_id));
}
if (!technical_level.empty()) {
Validate::text("technical_level", technical_level, AdminCaps::kMaxRoleChars);
o.set("technical_level", Json(technical_level));
}
if (!developer_persona.empty()) {
Validate::text("developer_persona", developer_persona, AdminCaps::kMaxRoleChars);
o.set("developer_persona", Json(developer_persona));
}
need_one(o, "user update");
return o;
}
Json ServiceAccountCreate::to_json() const {
Validate::text("name", name, AdminCaps::kMaxNameChars);
check_expiry(expires_in_seconds);
Json o = Json::object();
o.set("name", Json(name));
if (create_service_account_only) o.set("create_service_account_only", Json(*create_service_account_only));
put_int(o, "expires_in_seconds", expires_in_seconds);
return o;
}
Json ServiceAccountUpdate::to_json() const {
Json o = Json::object();
if (!name.empty()) {
Validate::text("name", name, AdminCaps::kMaxNameChars);
o.set("name", Json(name));
}
if (!role.empty()) {
Validate::one_of("role", role, {"member", "owner"});
o.set("role", Json(role));
}
need_one(o, "service account update");
return o;
}
Json ServiceAccountKeyCreate::to_json() const {
Json o = Json::object();
if (!name.empty()) {
Validate::text("name", name, AdminCaps::kMaxNameChars);
o.set("name", Json(name));
}
if (!scopes.empty()) {
check_scopes(scopes);
o.set("scopes", string_array(scopes));
}
check_expiry(expires_in_seconds);
put_int(o, "expires_in_seconds", expires_in_seconds);
return o;
}
Json ProjectApiKeyUpdate::to_json() const {
Json o = Json::object();
check_expiry(expires_in_seconds);
put_int(o, "expires_in_seconds", expires_in_seconds);
if (scopes) {
check_scopes(*scopes);
o.set("scopes", string_array(*scopes));
}
need_one(o, "project api key update");
return o;
}
Json RateLimitUpdate::to_json() const {
Json o = Json::object();
const std::pair<const char*, const std::optional<std::int64_t>*> fields[] = {
{"max_requests_per_1_minute", &max_requests_per_1_minute},
{"max_tokens_per_1_minute", &max_tokens_per_1_minute},
{"max_images_per_1_minute", &max_images_per_1_minute},
{"max_audio_megabytes_per_1_minute", &max_audio_megabytes_per_1_minute},
{"max_requests_per_1_day", &max_requests_per_1_day},
{"batch_1_day_max_input_tokens", &batch_1_day_max_input_tokens}};
for (const auto& [name, value] : fields) {
if (!*value) continue;
Validate::range(name, **value, 0, 1000000000000LL);
o.set(name, Json(static_cast<long>(**value)));
}
need_one(o, "rate limit update");
return o;
}
Json CertificateUpload::to_json() const {
Validate::text("certificate", certificate, AdminCaps::kMaxCertificatePemBytes);
if (certificate.find("-----BEGIN CERTIFICATE-----") == std::string::npos)
Validate::fail("certificate must be a PEM CERTIFICATE block");
if (certificate.find("PRIVATE KEY") != std::string::npos)
Validate::fail("certificate contains a private key; upload the public certificate only");
Json o = Json::object();
o.set("certificate", Json(certificate));
if (!name.empty()) {
Validate::text("name", name, AdminCaps::kMaxNameChars);
o.set("name", Json(name));
}
return o;
}
Json SpendAlertSpec::to_json() const {
Validate::range("threshold_amount", threshold_amount, 1, 1000000000000LL);
Validate::count("recipients", recipients.size(), 10, false);
Json channel = Json::object();
channel.set("type", Json("email"));
Json to = Json::array();
for (const std::string& r : recipients) {
Validate::email(r);
to.push(Json(r));
}
channel.set("recipients", to);
if (!subject_prefix.empty()) {
Validate::text("subject_prefix", subject_prefix, AdminCaps::kMaxNameChars);
channel.set("subject_prefix", Json(subject_prefix));
}
Json o = Json::object();
o.set("threshold_amount", Json(static_cast<long>(threshold_amount)));
o.set("currency", Json("USD"));
o.set("interval", Json("month"));
o.set("notification_channel", channel);
return o;
}
Json SpendLimitSpec::to_json() const {
Validate::range("threshold_amount", threshold_amount, 1, 1000000000000LL);
Json o = Json::object();
o.set("threshold_amount", Json(static_cast<long>(threshold_amount)));
o.set("currency", Json("USD"));
o.set("interval", Json("month"));
return o;
}
Json RoleSpec::to_json() const {
Validate::text("role_name", role_name, AdminCaps::kMaxNameChars);
Validate::count("permissions", permissions.size(), AdminCaps::kMaxPermissions, false);
for (const std::string& p : permissions) Validate::text("permission", p, AdminCaps::kMaxNameChars);
Json o = Json::object();
o.set("role_name", Json(role_name));
o.set("permissions", string_array(permissions));
if (!description.empty()) {
Validate::text("description", description, AdminCaps::kMaxDescriptionChars);
o.set("description", Json(description));
}
return o;
}
Json RoleUpdate::to_json() const {
Json o = Json::object();
if (!role_name.empty()) {
Validate::text("role_name", role_name, AdminCaps::kMaxNameChars);
o.set("role_name", Json(role_name));
}
if (permissions) {
Validate::count("permissions", permissions->size(), AdminCaps::kMaxPermissions, false);
for (const std::string& p : *permissions) Validate::text("permission", p, AdminCaps::kMaxNameChars);
o.set("permissions", string_array(*permissions));
}
if (!description.empty()) {
Validate::text("description", description, AdminCaps::kMaxDescriptionChars);
o.set("description", Json(description));
}
need_one(o, "role update");
return o;
}
Json ModelPermissions::to_json() const {
Validate::one_of("mode", mode, {"allow_list", "deny_list"});
Validate::count("model_ids", model_ids.size(), AdminCaps::kMaxModelIds, false);
for (const std::string& m : model_ids) Validate::text("model id", m, AdminCaps::kMaxNameChars);
Json o = Json::object();
o.set("mode", Json(mode));
o.set("model_ids", string_array(model_ids));
return o;
}
const std::vector<std::string>& HostedToolPermissions::tools() {
static const std::vector<std::string> t = {"file_search", "web_search", "image_generation", "mcp",
"code_interpreter"};
return t;
}
Json HostedToolPermissions::to_json() const {
Json o = Json::object();
for (const auto& [tool, on] : enabled) {
if (std::find(tools().begin(), tools().end(), tool) == tools().end())
Validate::fail("unknown hosted tool " + tool);
Json e = Json::object();
e.set("enabled", Json(on));
o.set(tool, e);
}
need_one(o, "hosted tool permissions");
return o;
}
Json DataRetention::organization(const std::string& retention_type) {
Validate::one_of("retention_type", retention_type,
{"zero_data_retention", "modified_abuse_monitoring",
"enhanced_zero_data_retention", "enhanced_modified_abuse_monitoring"});
Json o = Json::object();
o.set("retention_type", Json(retention_type));
return o;
}
Json DataRetention::project(const std::string& retention_type) {
Validate::one_of("retention_type", retention_type,
{"organization_default", "none", "zero_data_retention",
"modified_abuse_monitoring", "enhanced_zero_data_retention",
"enhanced_modified_abuse_monitoring"});
Json o = Json::object();
o.set("retention_type", Json(retention_type));
return o;
}
Json ExternalStorageSpec::to_json() const {
Validate::id("project_id", project_id);
Validate::one_of("provider type", type, {"aws", "azure", "gcp", "oci"});
static const std::map<std::string, std::vector<std::string>> required = {
{"aws", {"bucket", "role_arn"}},
{"azure", {"tenant_id", "subscription_id", "resource_group", "account_name", "container"}},
{"gcp",
{"bucket", "workload_identity_project_number", "workload_identity_pool_id",
"workload_identity_provider_id"}},
{"oci", {"tenancy_ocid", "region", "bucket"}}};
const auto& need = required.at(type);
for (const auto& [k, v] : provider) {
if (std::find(need.begin(), need.end(), k) == need.end())
Validate::fail("provider " + type + " has no field " + k);
Validate::text(k, v, AdminCaps::kMaxNameChars);
}
Json p = Json::object();
p.set("type", Json(type));
for (const std::string& k : need) {
auto it = provider.find(k);
if (it == provider.end()) Validate::fail("provider " + type + " needs " + k);
p.set(k, Json(it->second));
}
Json o = Json::object();
o.set("project_id", Json(project_id));
o.set("provider", p);
return o;
}
Json WebhookEndpointSpec::to_json(bool for_create) const {
Json o = Json::object();
if (for_create || !name.empty()) {
Validate::text("name", name, AdminCaps::kMaxNameChars);
o.set("name", Json(name));
}
if (for_create || !url.empty()) {
Validate::https_url("url", url, AdminCaps::kMaxWebhookUrlChars);
o.set("url", Json(url));
}
if (for_create || !event_types.empty()) {
Validate::count("event_types", event_types.size(), AdminCaps::kMaxEndpointEventTypes, false);
for (const std::string& t : event_types)
if (!WebhookEvents::is_subscribable(t)) Validate::fail("event type " + t + " cannot be subscribed to");
o.set("event_types", string_array(event_types));
}
if (!for_create) need_one(o, "webhook endpoint update");
return o;
}
} // namespace molo::openai::admin
+167
View File
@@ -0,0 +1,167 @@
#pragma once
// Typed request bodies. Every class validates in `to_json()` (ranges and
// enums taken from the OpenAPI document, ceilings from AdminCaps) and throws
// llm::ApiError::invalid before anything is sent. Optional fields that are
// unset are left out of the body, never sent as null.
#include <cstdint>
#include <map>
#include <optional>
#include <string>
#include <vector>
#include "clients/body/json.h"
namespace molo::openai::admin {
using Json = clients::body::Json;
// Longest expiry the API accepts for a key (1 year, spec maximum).
constexpr std::int64_t kMaxKeyExpirySeconds = 31536000;
struct ProjectGrant {
std::string id;
std::string role; // member | owner
};
struct InviteRequest {
std::string email;
std::string role; // reader | owner
std::vector<ProjectGrant> projects;
Json to_json() const;
};
struct ProjectCreate {
std::string name;
std::string residency; // PublicProjectResidency value, optional
std::string geography; // deprecated spelling, optional
std::string external_key_id; // optional
Json to_json() const;
};
struct ProjectUpdate {
std::string name;
std::string external_key_id;
std::string geography;
Json to_json() const; // at least one field
};
struct ProjectUserCreate {
std::string user_id; // exactly one of user_id / email
std::string email;
std::string role; // owner | member
Json to_json() const;
};
struct UserUpdate {
std::string role; // owner | reader
std::string role_id;
std::string technical_level;
std::string developer_persona;
Json to_json() const; // at least one field
};
struct ServiceAccountCreate {
std::string name;
std::optional<bool> create_service_account_only;
std::optional<std::int64_t> expires_in_seconds;
Json to_json() const;
};
struct ServiceAccountUpdate {
std::string name;
std::string role; // member | owner
Json to_json() const; // at least one field
};
struct ServiceAccountKeyCreate {
std::string name;
std::vector<std::string> scopes;
std::optional<std::int64_t> expires_in_seconds;
Json to_json() const;
};
struct ProjectApiKeyUpdate {
std::optional<std::int64_t> expires_in_seconds;
std::optional<std::vector<std::string>> scopes; // empty vector removes the restriction
Json to_json() const; // at least one field
};
struct RateLimitUpdate {
std::optional<std::int64_t> max_requests_per_1_minute;
std::optional<std::int64_t> max_tokens_per_1_minute;
std::optional<std::int64_t> max_images_per_1_minute;
std::optional<std::int64_t> max_audio_megabytes_per_1_minute;
std::optional<std::int64_t> max_requests_per_1_day;
std::optional<std::int64_t> batch_1_day_max_input_tokens;
Json to_json() const; // at least one field
};
struct CertificateUpload {
std::string name; // optional
std::string certificate; // PEM
Json to_json() const;
};
// Spend alert: USD per month, threshold in cents (spec: integer, minimum 1).
struct SpendAlertSpec {
std::int64_t threshold_amount = 0;
std::vector<std::string> recipients; // email channel, 1..10
std::string subject_prefix; // optional
Json to_json() const;
};
struct SpendLimitSpec {
std::int64_t threshold_amount = 0; // cents, minimum 1
Json to_json() const;
};
struct RoleSpec {
std::string role_name;
std::vector<std::string> permissions;
std::string description; // optional
Json to_json() const;
};
struct RoleUpdate {
std::string role_name;
std::optional<std::vector<std::string>> permissions;
std::string description;
Json to_json() const; // at least one field
};
struct ModelPermissions {
std::string mode; // allow_list | deny_list
std::vector<std::string> model_ids;
Json to_json() const;
};
// file_search, web_search, image_generation, mcp, code_interpreter -> enabled.
struct HostedToolPermissions {
std::map<std::string, bool> enabled;
Json to_json() const; // at least one tool
static const std::vector<std::string>& tools();
};
// Retention types of the spec: organization and project enums differ.
struct DataRetention {
static Json organization(const std::string& retention_type);
static Json project(const std::string& retention_type);
};
struct ExternalStorageSpec {
std::string project_id;
std::string type; // aws | azure | gcp | oci
std::map<std::string, std::string> provider; // fields of that provider, see SPEC
Json to_json() const;
};
struct WebhookEndpointSpec {
std::string name;
std::string url;
std::vector<std::string> event_types;
Json to_json(bool for_create) const; // update needs at least one field
};
} // namespace molo::openai::admin
+272
View File
@@ -0,0 +1,272 @@
#!/usr/bin/env python3
"""Check src/openai/admin against OpenAI's published OpenAPI document.
Fails (exit 1) when a declared call is absent from the spec, its HTTP method,
path, operationId, auth scheme, query parameters, request body fields,
required fields or response schema differ, when a schema field we read is
absent, when the audit event or webhook event catalogs differ, or when a spec
operation in scope (organization administration, webhook endpoints) is neither
in the call table nor in the explicit EXCLUDED list below. Python 3 stdlib
only, no credentials.
python3 -I src/openai/admin/tools/check_spec.py # pinned revision
python3 -I src/openai/admin/tools/check_spec.py --head # newest main
python3 -I src/openai/admin/tools/check_spec.py --file x.json
Second source: the official openai-go SDK api.md must list every table row's
HTTP method and path (cross-check, rule 2 of plan 17).
"""
import json
import os
import re
import sys
import urllib.request
HERE = os.path.dirname(os.path.abspath(__file__))
SRC = os.path.join(HERE, "..")
PINNED = "8243cc8fa6f04430fb1f1a6a2cb926fbeb4f7f26"
SPEC_URL = "https://raw.githubusercontent.com/openai/openai-openapi/%s/openapi.json"
GO_API = "https://raw.githubusercontent.com/openai/openai-go/main/api.md"
GO_WEBHOOKS_API = "https://raw.githubusercontent.com/openai/openai-go/main/webhooks/api.md"
# Spec operations in scope that this package deliberately does not wrap:
# method path -> reason. Empty: every in-scope operation is wrapped.
EXCLUDED = {}
ROW = re.compile(r'^\s*\{(.*)\},?\s*$')
STR = re.compile(r'"((?:[^"\\]|\\.)*)"')
def fetch(url):
req = urllib.request.Request(url, headers={"User-Agent": "molo-check-spec"})
with urllib.request.urlopen(req, timeout=300) as r:
return r.read()
def block(text, begin, end):
a = text.index(begin)
b = text.index(end)
rows = []
for line in text[a:b].splitlines()[1:]:
m = ROW.match(line)
if m and '"' in line:
rows.append(STR.findall(m.group(1)))
return rows
def strings_block(text, begin, end):
a = text.index(begin)
b = text.index(end)
return STR.findall(text[a:b].split("\n", 1)[1])
def in_scope(path):
return path.startswith("/organization") or path.startswith("/webhook_endpoints") \
or path == "/webhook_event_types"
def main():
args = sys.argv[1:]
if "--file" in args:
raw = open(args[args.index("--file") + 1], "rb").read()
label = args[args.index("--file") + 1]
else:
sha = PINNED
if "--head" in args:
meta = json.loads(fetch("https://api.github.com/repos/openai/openai-openapi/commits/main"))
sha = meta["sha"]
raw = fetch(SPEC_URL % sha)
label = sha
spec = json.loads(raw)
schemas = spec["components"]["schemas"]
paths = spec["paths"]
def deref(x):
while isinstance(x, dict) and "$ref" in x:
x = schemas[x["$ref"].split("/")[-1]] if x["$ref"].startswith("#/components/schemas/") \
else resolve(x["$ref"])
return x
def resolve(ref):
node = spec
for part in ref.lstrip("#/").split("/"):
node = node[part]
return node
def flat(sch):
sch = deref(sch)
props, req = dict(sch.get("properties", {})), list(sch.get("required", []))
for a in sch.get("allOf", []):
p, r = flat(a)
props.update(p)
req += r
return props, req
calls_src = open(os.path.join(SRC, "calls.cpp")).read()
calls = block(calls_src, "// CALLS-BEGIN", "// CALLS-END")
fields = block(calls_src, "// SCHEMAS-BEGIN", "// SCHEMAS-END")
bad = []
default_security = spec.get("security", [])
for key, http, path, op_id, auth, body, req, query, rschema, resp, flags in \
[tuple(r[:11]) for r in calls]:
node = paths.get(path, {}).get(http.lower())
if not node:
bad.append("%s: %s %s absent from the spec" % (key, http, path))
continue
if node.get("operationId") != op_id:
bad.append("%s: operationId %s != %s" % (key, op_id, node.get("operationId")))
sec = node.get("security", default_security)
scheme = list(sec[0].keys())[0] if sec else ""
want = "AdminApiKeyAuth" if auth == "admin" else "ApiKeyAuth"
if scheme != want:
bad.append("%s: auth %s but the spec says %s" % (key, auth, scheme))
if auth == "project" and "AdminApiKeyAuth" in json.dumps(sec):
bad.append("%s: project call declared with admin security" % key)
spec_query = []
for prm in node.get("parameters", []):
prm = deref(prm)
if prm["in"] == "query":
spec_query.append(prm["name"])
mine = [q for q in query.split(",") if q]
for q in mine:
if q not in spec_query:
bad.append("%s: query parameter %s absent" % (key, q))
for q in spec_query:
if q not in mine:
bad.append("%s: spec query parameter %s not in the table" % (key, q))
want_path_params = re.findall(r"\{([^}]+)\}", path)
spec_path_params = [deref(p)["name"] for p in node.get("parameters", []) if deref(p)["in"] == "path"]
if sorted(want_path_params) != sorted(spec_path_params):
bad.append("%s: path parameters %s != %s" % (key, want_path_params, spec_path_params))
rb = node.get("requestBody")
if rb:
sch = rb["content"]["application/json"]["schema"]
ref = sch["$ref"].split("/")[-1] if "$ref" in sch else ""
if ref != rschema:
bad.append("%s: request schema %r != %r" % (key, rschema, ref))
props, reqd = flat(sch)
for f in [f for f in body.split(",") if f]:
if f not in props:
bad.append("%s: body field %s absent" % (key, f))
for f in props:
if f not in body.split(","):
bad.append("%s: spec body field %s not in the table" % (key, f))
if sorted(set(reqd)) != sorted(f for f in req.split(",") if f):
bad.append("%s: required %s != %s" % (key, sorted(set(reqd)), req))
elif body or req or rschema:
bad.append("%s: table has a body but the spec has none" % key)
ok = node["responses"].get("200") or node["responses"].get("201")
content = deref(ok).get("content", {}).get("application/json") if ok else None
got = content["schema"]["$ref"].split("/")[-1] if content and "$ref" in content["schema"] else ""
if got != resp:
bad.append("%s: response schema %r != %r" % (key, resp, got))
if (http == "DELETE") != (flags == "destructive") and key not in (
"projects.archive", "certificates.deactivate", "projects.certificates.deactivate",
"data_retention.update", "projects.data_retention.update",
"webhook_endpoints.rotate_secret"):
bad.append("%s: destructive flag disagrees with the HTTP method" % key)
for name, flds in fields:
sch = schemas.get(name)
if sch is None:
bad.append("missing schema %s" % name)
continue
props, _ = flat(sch)
for f in flds.split(","):
if f not in props:
bad.append("schema %s.%s absent" % (name, f))
declared = {(r[1], r[2]) for r in calls}
in_scope_ops = 0
for path, item in paths.items():
if not in_scope(path):
continue
for method in ("get", "post", "put", "patch", "delete"):
if method in item:
in_scope_ops += 1
k = (method.upper(), path)
if k not in declared and ("%s %s" % k) not in EXCLUDED:
bad.append("unwrapped spec operation %s %s" % k)
for ex in EXCLUDED:
m, p = ex.split(" ", 1)
if (m, p) in declared:
bad.append("excluded operation %s is also in the table" % ex)
# Audit event type catalog.
audit_src = open(os.path.join(SRC, "audit_events.cpp")).read()
mine = strings_block(audit_src, "// AUDIT-EVENTS-BEGIN", "// AUDIT-EVENTS-END")
theirs = schemas["AuditLogEventType"]["enum"]
if mine != theirs:
bad.append("audit event catalog differs: missing %s extra %s" % (
[e for e in theirs if e not in mine], [e for e in mine if e not in theirs]))
# Webhook catalogs.
wh_src = open(os.path.join(SRC, "webhook_events.cpp")).read()
sent = strings_block(wh_src, "// WEBHOOK-EVENTS-BEGIN", "// WEBHOOK-EVENTS-END")
spec_sent = []
for name, item in spec.get("webhooks", {}).items():
sch = item["post"]["requestBody"]["content"]["application/json"]["schema"]
props, _ = flat(sch)
enum = deref(props["type"]).get("enum")
spec_sent += enum or []
if sorted(sent) != sorted(spec_sent):
bad.append("webhook event types differ: missing %s extra %s" % (
sorted(set(spec_sent) - set(sent)), sorted(set(sent) - set(spec_sent))))
sub = strings_block(wh_src, "// SUBSCRIBABLE-BEGIN", "// SUBSCRIBABLE-END")
if sub != schemas["ProjectEventTypeEnum"]["enum"]:
bad.append("subscribable webhook event types differ from ProjectEventTypeEnum")
usage_src = open(os.path.join(SRC, "usage.cpp")).read()
ub = usage_src[usage_src.index("// USAGE-ENDPOINTS-BEGIN"):usage_src.index("// USAGE-ENDPOINTS-END")]
for name, gb in re.findall(r'"(\w+)", Call::\w+,\s*"([^"]*)"\}', ub):
node = paths["/organization/usage/" + name]["get"]
enum = []
for prm in node["parameters"]:
prm = deref(prm)
if prm["name"] == "group_by":
it = deref(prm["schema"]).get("items")
enum = deref(it).get("enum", []) if it else []
if enum != [g for g in gb.split(",") if g]:
bad.append("usage %s group_by %s != spec %s" % (name, gb, enum))
spec_res = [n for n in schemas if n.startswith("Usage") and n.endswith("Result")] + ["CostsResult"]
for n in spec_res:
if n not in [f[0] for f in fields]:
bad.append("usage result schema %s is not in the SCHEMAS table" % n)
evb = wh_src[wh_src.index("// EVENT-SPECS"):wh_src.index("// WEBHOOK-EVENTS-BEGIN")]
rows_ev = re.findall(r'\{"([^"]+)", "([^"]+)", "([^"]*)", "([^"]*)"\}', evb)
for t, key, flds, rq in rows_ev:
item = spec["webhooks"].get(key)
if not item:
bad.append("webhook %s absent" % key)
continue
props, _ = flat(item["post"]["requestBody"]["content"]["application/json"]["schema"])
dp, dr = flat(props["data"])
if sorted(dp) != sorted(flds.split(",")) or sorted(set(dr)) != sorted(x for x in rq.split(",") if x):
bad.append("webhook %s data fields differ" % t)
# Second source: openai-go api.md lists every method and path.
sdk = fetch(GO_API).decode() + fetch(GO_WEBHOOKS_API).decode()
listed = set(re.findall(r'title="(get|post|delete) (/[^"]+)"', sdk))
miss = 0
for r in calls:
http, path = r[1].lower(), r[2]
sdk_path = path[1:] if (http, path[1:]) in listed else path
if (http, sdk_path) not in listed and (http, path.lstrip("/")) not in listed:
miss += 1
bad.append("openai-go api.md does not list %s %s" % (http.upper(), path))
if bad:
print("SPEC CHECK FAILED (%s)" % label)
for b in bad:
print(" " + b)
return 1
print("spec ok: %d calls, %d schemas, %d in-scope spec operations covered, "
"%d audit event types, %d sent webhook event types, openai-go lists all %d rows, "
"openapi %s revision %s, info.version %s"
% (len(calls), len(fields), in_scope_ops, len(theirs), len(spec_sent), len(calls) - miss,
"openapi.json", label, spec["info"]["version"]))
return 0
if __name__ == "__main__":
sys.exit(main())
+53
View File
@@ -0,0 +1,53 @@
#!/usr/bin/env python3
"""Unauthenticated probe: every GET row of calls.cpp must answer 401 (path
exists, auth required) and a made-up sibling must answer 404. Sends an
obviously invalid key, never a real credential. Python 3 stdlib only.
python3 -I src/openai/admin/tools/probe_paths.py
"""
import os
import re
import sys
import urllib.error
import urllib.request
HERE = os.path.dirname(os.path.abspath(__file__))
BASE = "https://api.openai.com/v1"
def status(path):
req = urllib.request.Request(BASE + path, headers={"Authorization": "Bearer sk-admin-invalid"})
try:
with urllib.request.urlopen(req, timeout=30) as r:
return r.status
except urllib.error.HTTPError as e:
return e.code
def main():
src = open(os.path.join(HERE, "..", "calls.cpp")).read()
src = src[src.index("// CALLS-BEGIN"):src.index("// CALLS-END")]
rows = [re.findall(r'"([^"]*)"', l) for l in src.splitlines() if l.strip().startswith("{Call::")]
bad, n = [], 0
for r in rows:
if r[1] != "GET":
continue
n += 1
path = re.sub(r"\{[^}]+\}", "probe_id", r[2])
code = status(path)
if code != 401:
bad.append("%s -> %s (want 401)" % (path, code))
code = status("/organization/nonexistent_probe_path")
if code != 404:
bad.append("made-up path -> %s (want 404)" % code)
if bad:
print("PROBE FAILED")
for b in bad:
print(" " + b)
return 1
print("probe ok: %d GET paths answered 401, made-up path answered 404" % n)
return 0
if __name__ == "__main__":
sys.exit(main())
+219
View File
@@ -0,0 +1,219 @@
#include "openai/admin/usage.h"
#include <algorithm>
#include "llm/error.h"
#include "openai/admin/caps.h"
#include "openai/admin/validate.h"
namespace molo::openai::admin {
namespace {
struct Endpoint {
UsageKind kind;
const char* name;
Call call;
const char* group_by; // comma list from the spec; "" = unconstrained
};
// USAGE-ENDPOINTS-BEGIN (name, group_by enum; checked by tools/check_spec.py)
const Endpoint kEndpoints[] = {
{UsageKind::kCompletions, "completions", Call::kUsageCompletions,
"project_id,user_id,api_key_id,model,batch,service_tier,api_source"},
{UsageKind::kEmbeddings, "embeddings", Call::kUsageEmbeddings,
"project_id,user_id,api_key_id,model"},
{UsageKind::kModerations, "moderations", Call::kUsageModerations,
"project_id,user_id,api_key_id,model"},
{UsageKind::kImages, "images", Call::kUsageImages,
"project_id,user_id,api_key_id,model,size,source"},
{UsageKind::kAudioSpeeches, "audio_speeches", Call::kUsageAudioSpeeches,
"project_id,user_id,api_key_id,model"},
{UsageKind::kAudioTranscriptions, "audio_transcriptions", Call::kUsageAudioTranscriptions,
"project_id,user_id,api_key_id,model"},
{UsageKind::kVectorStores, "vector_stores", Call::kUsageVectorStores, "project_id"},
{UsageKind::kCodeInterpreterSessions, "code_interpreter_sessions",
Call::kUsageCodeInterpreterSessions, "project_id"},
{UsageKind::kFileSearchCalls, "file_search_calls", Call::kUsageFileSearchCalls,
"project_id,user_id,api_key_id,vector_store_id"},
{UsageKind::kWebSearchCalls, "web_search_calls", Call::kUsageWebSearchCalls,
"project_id,user_id,api_key_id,model,context_level,api_source"},
{UsageKind::kDecisions, "decisions", Call::kUsageDecisions, ""},
};
// USAGE-ENDPOINTS-END
const Endpoint& endpoint(UsageKind kind) {
for (const Endpoint& e : kEndpoints)
if (e.kind == kind) return e;
Validate::fail("unknown usage endpoint");
}
int max_buckets(const std::string& width) {
if (width == "1m") return AdminCaps::kMaxBuckets1m;
if (width == "1h") return AdminCaps::kMaxBuckets1h;
return AdminCaps::kMaxBuckets1d;
}
void common(Query& q, std::int64_t start, const std::optional<std::int64_t>& end,
const std::string& page) {
Validate::epoch("start_time", start);
q.set_int("start_time", start);
if (end) {
Validate::epoch("end_time", *end);
if (*end <= start) Validate::fail("end_time must be after start_time");
q.set_int("end_time", *end);
}
if (!page.empty()) q.set("page", page);
}
void group_by_check(const std::vector<std::string>& values, const std::vector<std::string>& allowed) {
Validate::count("group_by", values.size(), AdminCaps::kMaxGroupBy, true);
for (const std::string& g : values) {
Validate::text("group_by", g, 64);
if (!allowed.empty() && std::find(allowed.begin(), allowed.end(), g) == allowed.end())
Validate::fail("group_by " + g + " is not allowed here");
}
}
void filter(Query& q, Call call, const char* name, const std::vector<std::string>& values) {
if (values.empty()) return;
if (!CallTable::allows_query(call, name))
Validate::fail(std::string(name) + " is not a filter of " + CallTable::spec(call).key);
q.add_all(name, values);
}
} // namespace
const std::vector<UsageKind>& UsageEndpoints::all() {
static const std::vector<UsageKind> kinds = [] {
std::vector<UsageKind> v;
for (const Endpoint& e : kEndpoints) v.push_back(e.kind);
return v;
}();
return kinds;
}
Call UsageEndpoints::call(UsageKind kind) { return endpoint(kind).call; }
std::string UsageEndpoints::name(UsageKind kind) { return endpoint(kind).name; }
std::optional<UsageKind> UsageEndpoints::parse(const std::string& name) {
for (const Endpoint& e : kEndpoints)
if (name == e.name) return e.kind;
return std::nullopt;
}
std::vector<std::string> UsageEndpoints::group_by(UsageKind kind) {
return CallTable::split(endpoint(kind).group_by);
}
Query UsageQuery::to_query(UsageKind kind) const {
const Call call = UsageEndpoints::call(kind);
Query q;
common(q, start_time, end_time, page);
if (!bucket_width.empty()) {
Validate::one_of("bucket_width", bucket_width, {"1m", "1h", "1d"});
q.set("bucket_width", bucket_width);
}
if (limit) {
Validate::range("limit", *limit, 1, max_buckets(bucket_width));
q.set_int("limit", *limit);
}
filter(q, call, "project_ids", project_ids);
filter(q, call, "user_ids", user_ids);
filter(q, call, "api_key_ids", api_key_ids);
filter(q, call, "models", models);
if (batch) {
if (!CallTable::allows_query(call, "batch")) Validate::fail("batch is not a filter here");
q.set_bool("batch", *batch);
}
group_by_check(group_by, UsageEndpoints::group_by(kind));
filter(q, call, "group_by", group_by);
for (const std::string& s : sources)
Validate::one_of("source", s, {"image.generation", "image.edit", "image.variation"});
for (const std::string& s : sizes)
Validate::one_of("size", s, {"256x256", "512x512", "1024x1024", "1792x1792", "1024x1792"});
filter(q, call, "sources", sources);
filter(q, call, "sizes", sizes);
filter(q, call, "vector_store_ids", vector_store_ids);
filter(q, call, "context_levels", context_levels);
return q;
}
Query CostQuery::to_query() const {
Query q;
common(q, start_time, end_time, page);
if (!bucket_width.empty()) {
Validate::one_of("bucket_width", bucket_width, {"1d"});
q.set("bucket_width", bucket_width);
}
if (limit) {
Validate::range("limit", *limit, 1, AdminCaps::kMaxCostBuckets);
q.set_int("limit", *limit);
}
filter(q, Call::kCosts, "project_ids", project_ids);
filter(q, Call::kCosts, "api_key_ids", api_key_ids);
filter(q, Call::kCosts, "line_items", line_items);
group_by_check(group_by, {"project_id", "user_id", "line_item", "api_key_id", "api_source"});
filter(q, Call::kCosts, "group_by", group_by);
return q;
}
AdminService::Json Usage::query(UsageKind kind, const UsageQuery& query) {
return execute(UsageEndpoints::call(kind), {}, query.to_query(kind));
}
WalkResult Usage::walk(UsageKind kind, const UsageQuery& query) {
UsageQuery first = query;
first.page.clear();
return AdminService::walk(UsageEndpoints::call(kind), {}, first.to_query(kind), "page", query.page);
}
AdminService::Json Costs::query(const CostQuery& query) {
return execute(Call::kCosts, {}, query.to_query());
}
WalkResult Costs::walk(const CostQuery& query) {
CostQuery first = query;
first.page.clear();
return AdminService::walk(Call::kCosts, {}, first.to_query(), "page", query.page);
}
const clients::body::Json::Array& UsageSummary::buckets_of(const clients::body::Json& doc) {
static const clients::body::Json::Array none;
if (doc.is_array()) return doc.as_array();
const clients::body::Json* data = doc.is_object() ? doc.find("data") : nullptr;
return data && data->is_array() ? data->as_array() : none;
}
std::map<std::string, double> UsageSummary::totals(const clients::body::Json& buckets) {
std::map<std::string, double> sum;
for (const auto& bucket : buckets_of(buckets)) {
const auto* results = bucket.is_object() ? bucket.find("results") : nullptr;
if (!results || !results->is_array()) continue;
for (const auto& r : results->as_array()) {
if (!r.is_object()) continue;
for (const auto& [name, value] : r.as_object())
if (value.is_number()) sum[name] += value.as_number();
}
}
return sum;
}
std::map<std::string, double> UsageSummary::cost_by_currency(const clients::body::Json& buckets) {
std::map<std::string, double> sum;
for (const auto& bucket : buckets_of(buckets)) {
const auto* results = bucket.is_object() ? bucket.find("results") : nullptr;
if (!results || !results->is_array()) continue;
for (const auto& r : results->as_array()) {
const auto* amount = r.is_object() ? r.find("amount") : nullptr;
if (!amount || !amount->is_object()) continue;
const auto* value = amount->find("value");
const auto* currency = amount->find("currency");
if (value && value->is_number())
sum[currency && currency->is_string() ? currency->as_string() : "unknown"] += value->as_number();
}
}
return sum;
}
} // namespace molo::openai::admin
+86
View File
@@ -0,0 +1,86 @@
#pragma once
// Usage and cost reports. One method per endpoint family, bucketed time
// series (bucket_width 1m / 1h / 1d, costs 1d only), group_by, filters and
// page-token paging ({object:"page", next_page}). A UsageQuery that sets a
// filter the endpoint does not have (for example `sizes` on completions) is
// rejected before any request.
#include <map>
#include <optional>
#include <string>
#include <vector>
#include "openai/admin/admin_service.h"
namespace molo::openai::admin {
enum class UsageKind {
kCompletions, kEmbeddings, kModerations, kImages, kAudioSpeeches, kAudioTranscriptions,
kVectorStores, kCodeInterpreterSessions, kFileSearchCalls, kWebSearchCalls, kDecisions
};
class UsageEndpoints {
public:
static const std::vector<UsageKind>& all();
static Call call(UsageKind kind);
static std::string name(UsageKind kind); // "completions", "audio_speeches", ...
static std::optional<UsageKind> parse(const std::string& name);
// group_by values the spec lists for the endpoint; empty = unconstrained.
static std::vector<std::string> group_by(UsageKind kind);
};
struct UsageQuery {
std::int64_t start_time = 0; // required, unix seconds, inclusive
std::optional<std::int64_t> end_time; // exclusive
std::string bucket_width; // 1m | 1h | 1d ("" = 1d)
std::optional<int> limit; // buckets; max depends on bucket_width
std::string page; // next_page token of the previous answer
std::vector<std::string> project_ids, user_ids, api_key_ids, models;
std::optional<bool> batch; // completions and decisions
std::vector<std::string> group_by;
std::vector<std::string> sources, sizes; // images
std::vector<std::string> vector_store_ids; // file search
std::vector<std::string> context_levels; // web search
Query to_query(UsageKind kind) const;
};
struct CostQuery {
std::int64_t start_time = 0;
std::optional<std::int64_t> end_time;
std::string bucket_width; // "1d" only
std::optional<int> limit; // 1..180
std::string page;
std::vector<std::string> project_ids, api_key_ids, line_items, group_by;
Query to_query() const;
};
class Usage : public AdminService {
public:
explicit Usage(std::shared_ptr<AdminApiClient> client) : AdminService(std::move(client)) {}
Json query(UsageKind kind, const UsageQuery& query);
// Follows next_page up to the page / item ceilings; truncation is reported.
WalkResult walk(UsageKind kind, const UsageQuery& query);
};
class Costs : public AdminService {
public:
explicit Costs(std::shared_ptr<AdminApiClient> client) : AdminService(std::move(client)) {}
Json query(const CostQuery& query);
WalkResult walk(const CostQuery& query);
};
// Totals over the buckets of one answer (or of a WalkResult::items array).
class UsageSummary {
public:
// Sum of every numeric field of every result ("input_tokens", "images", ...).
static std::map<std::string, double> totals(const clients::body::Json& buckets);
// Sum of amount.value per currency over cost results.
static std::map<std::string, double> cost_by_currency(const clients::body::Json& buckets);
// The bucket array of an answer ({data:[...]}) or the array itself.
static const clients::body::Json::Array& buckets_of(const clients::body::Json& doc);
};
} // namespace molo::openai::admin
+69
View File
@@ -0,0 +1,69 @@
#include "openai/admin/validate.h"
#include "llm/api_client.h"
#include "llm/error.h"
#include "openai/admin/caps.h"
namespace molo::openai::admin {
void Validate::fail(const std::string& message) {
throw llm::ApiError::invalid("openai", message);
}
void Validate::text(const std::string& what, const std::string& value, std::size_t max,
bool allow_empty) {
if (value.empty() && !allow_empty) fail(what + " is required");
if (value.size() > max) fail(what + " is over " + std::to_string(max) + " chars");
for (unsigned char c : value)
if (c < 0x20 || c == 0x7f) fail(what + " has a control character");
}
void Validate::id(const std::string& what, const std::string& value) {
if (!llm::Service::valid_id(value)) fail("bad " + what);
}
void Validate::one_of(const std::string& what, const std::string& value,
std::initializer_list<const char*> allowed) {
std::string list;
for (const char* a : allowed) {
if (value == a) return;
list += (list.empty() ? "" : ", ") + std::string(a);
}
fail(what + " must be one of: " + list);
}
void Validate::email(const std::string& value) {
text("email", value, AdminCaps::kMaxEmailChars);
const std::size_t at = value.find('@');
if (at == std::string::npos || at == 0 || at + 1 >= value.size() ||
value.find('@', at + 1) != std::string::npos || value.find(' ') != std::string::npos ||
value.find('.', at) == std::string::npos)
fail("email is not an address");
}
void Validate::range(const std::string& what, std::int64_t value, std::int64_t lo,
std::int64_t hi) {
if (value < lo || value > hi)
fail(what + " must be " + std::to_string(lo) + ".." + std::to_string(hi));
}
void Validate::count(const std::string& what, std::size_t n, std::size_t max, bool allow_empty) {
if (n == 0 && !allow_empty) fail(what + " needs at least one entry");
if (n > max) fail(what + " has more than " + std::to_string(max) + " entries");
}
void Validate::epoch(const std::string& what, std::int64_t value) {
range(what, value, 1, AdminCaps::kMaxTimeSeconds);
}
void Validate::https_url(const std::string& what, const std::string& value, std::size_t max) {
text(what, value, max);
if (value.rfind("https://", 0) != 0 || value.size() < 12 || value.find(' ') != std::string::npos)
fail(what + " must be an https:// URL");
}
void Validate::confirmed(const std::string& action, bool confirm) {
if (!confirm) fail(action + " is destructive: pass confirm=true to run it");
}
} // namespace molo::openai::admin
+36
View File
@@ -0,0 +1,36 @@
#pragma once
// Input validation shared by every request class and service. Every failure
// is an llm::ApiError::invalid (HTTP 400 INVALID_ARGUMENT, vendor "openai")
// raised before any network traffic.
#include <cstddef>
#include <cstdint>
#include <initializer_list>
#include <string>
namespace molo::openai::admin {
class Validate {
public:
[[noreturn]] static void fail(const std::string& message);
// 1..max chars (0 allowed when allow_empty), no control characters.
static void text(const std::string& what, const std::string& value, std::size_t max,
bool allow_empty = false);
// One URL path segment accepted by llm::Service::valid_id.
static void id(const std::string& what, const std::string& value);
static void one_of(const std::string& what, const std::string& value,
std::initializer_list<const char*> allowed);
static void email(const std::string& value);
static void range(const std::string& what, std::int64_t value, std::int64_t lo,
std::int64_t hi);
static void count(const std::string& what, std::size_t n, std::size_t max, bool allow_empty);
// Unix seconds in (0, kMaxTimeSeconds].
static void epoch(const std::string& what, std::int64_t value);
static void https_url(const std::string& what, const std::string& value, std::size_t max);
// Destructive calls need an explicit true; there is no default anywhere.
static void confirmed(const std::string& action, bool confirm);
};
} // namespace molo::openai::admin
+205
View File
@@ -0,0 +1,205 @@
#include "openai/admin/webhook_events.h"
#include <algorithm>
#include <iterator>
#include "llm/error.h"
#include "openai/admin/caps.h"
#include "openai/admin/validate.h"
namespace molo::openai::admin {
using clients::body::Json;
// EVENT-SPECS (payload description per event; `webhooks` map of the OpenAPI document)
static const WebhookEventSpec kEvents[] = {
{"agent.environment.expired", "agent_environment_expired", "id", "id"},
{"agent.environment.failed", "agent_environment_failed", "id", "id"},
{"agent.environment.ready", "agent_environment_ready", "id", "id"},
{"agent.environment.suspended", "agent_environment_suspended", "id", "id"},
{"agent.session.action_required", "agent_session_action_required", "id,required_action", "id,required_action"},
{"agent.session.created", "agent_session_created", "id,environment_id,environment_type,connect", "id,environment_type"},
{"agent.session.failed", "agent_session_failed", "id,environment_id,environment_type", "id,environment_type"},
{"agent.session.idle", "agent_session_idle", "id,environment_id,environment_type", "id,environment_type"},
{"agent.session.in_progress", "agent_session_in_progress", "id,environment_id,environment_type", "id,environment_type"},
{"batch.cancelled", "batch_cancelled", "id", "id"},
{"batch.completed", "batch_completed", "id", "id"},
{"batch.expired", "batch_expired", "id", "id"},
{"batch.failed", "batch_failed", "id", "id"},
{"eval.run.canceled", "eval_run_canceled", "id", "id"},
{"eval.run.failed", "eval_run_failed", "id", "id"},
{"eval.run.succeeded", "eval_run_succeeded", "id", "id"},
{"fine_tuning.job.cancelled", "fine_tuning_job_cancelled", "id", "id"},
{"fine_tuning.job.failed", "fine_tuning_job_failed", "id", "id"},
{"fine_tuning.job.succeeded", "fine_tuning_job_succeeded", "id", "id"},
{"live.call.incoming", "live_call_incoming", "session_id,sip_media_security,sip_headers", "session_id,sip_headers"},
{"live.transport.incoming", "live_transport_incoming", "type,session_id,sip_media_security,sip_headers", "type,session_id,sip_headers"},
{"realtime.call.incoming", "realtime_call_incoming", "call_id,sip_media_security,sip_headers", "call_id,sip_headers"},
{"response.cancelled", "response_cancelled", "id", "id"},
{"response.completed", "response_completed", "id", "id"},
{"response.failed", "response_failed", "id", "id"},
{"response.incomplete", "response_incomplete", "id", "id"},
{"safety.alert.created", "safety_alert_created", "id", "id"},
{"safety.deactivation_issued", "safety_deactivation_issued", "id", "id"},
{"safety.org_alert.created", "safety_org_alert_created", "id", "id"},
{"safety.warning_issued", "safety_warning_issued", "id", "id"},
};
// WEBHOOK-EVENTS-BEGIN (types of kEvents; checked by tools/check_spec.py)
static const char* const kSent[] = {
"agent.environment.expired",
"agent.environment.failed",
"agent.environment.ready",
"agent.environment.suspended",
"agent.session.action_required",
"agent.session.created",
"agent.session.failed",
"agent.session.idle",
"agent.session.in_progress",
"batch.cancelled",
"batch.completed",
"batch.expired",
"batch.failed",
"eval.run.canceled",
"eval.run.failed",
"eval.run.succeeded",
"fine_tuning.job.cancelled",
"fine_tuning.job.failed",
"fine_tuning.job.succeeded",
"live.call.incoming",
"live.transport.incoming",
"realtime.call.incoming",
"response.cancelled",
"response.completed",
"response.failed",
"response.incomplete",
"safety.alert.created",
"safety.deactivation_issued",
"safety.org_alert.created",
"safety.warning_issued",
};
// WEBHOOK-EVENTS-END
// SUBSCRIBABLE-BEGIN (ProjectEventTypeEnum; checked by tools/check_spec.py)
static const char* const kSubscribable[] = {
"batch.completed",
"batch.failed",
"batch.expired",
"batch.cancelled",
"response.completed",
"response.failed",
"response.cancelled",
"response.incomplete",
"eval.run.succeeded",
"eval.run.failed",
"eval.run.canceled",
"fine_tuning.job.succeeded",
"fine_tuning.job.failed",
"fine_tuning.job.cancelled",
"realtime.call.incoming",
"video.completed",
"video.failed",
"agent.environment.ready",
"agent.environment.failed",
"agent.environment.suspended",
"agent.environment.expired",
"agent.session.created",
"agent.session.action_required",
"agent.session.in_progress",
"agent.session.idle",
"agent.session.failed",
"safety.alert.created",
};
// SUBSCRIBABLE-END
std::size_t WebhookEvents::count() { return sizeof(kEvents) / sizeof(kEvents[0]); }
const WebhookEventSpec& WebhookEvents::at(std::size_t index) {
if (index >= count()) Validate::fail("webhook event index out of range");
return kEvents[index];
}
const WebhookEventSpec* WebhookEvents::find(const std::string& type) {
for (const WebhookEventSpec& e : kEvents)
if (type == e.type) return &e;
return nullptr;
}
const std::vector<std::string>& WebhookEvents::sent() {
static const std::vector<std::string> v(std::begin(kSent), std::end(kSent));
return v;
}
const std::vector<std::string>& WebhookEvents::subscribable() {
static const std::vector<std::string> v(std::begin(kSubscribable), std::end(kSubscribable));
return v;
}
bool WebhookEvents::is_subscribable(const std::string& type) {
const auto& v = subscribable();
return std::find(v.begin(), v.end(), type) != v.end();
}
std::string WebhookEvent::family() const { return type.substr(0, type.find('.')); }
std::string WebhookEvent::resource_id() const {
const Json* id_field = data.is_object() ? data.find("id") : nullptr;
return id_field && id_field->is_string() ? id_field->as_string() : "";
}
Json WebhookEvent::to_json() const {
Json o = Json::object();
o.set("id", Json(id));
o.set("type", Json(type));
o.set("created_at", Json(static_cast<long>(created_at)));
o.set("family", Json(family()));
o.set("resource_id", Json(resource_id()));
o.set("known", Json(known));
Json missing = Json::array();
for (const std::string& m : missing_data_fields) missing.push(Json(m));
o.set("missing_data_fields", missing);
o.set("data", data);
return o;
}
WebhookEvent WebhookEnvelope::parse(const std::string& body) {
if (body.size() > AdminCaps::kMaxWebhookBodyBytes) Validate::fail("webhook body over the cap");
Json doc;
try {
doc = Json::parse(body);
} catch (const std::exception&) {
Validate::fail("webhook body is not JSON");
}
if (!doc.is_object()) Validate::fail("webhook body is not an object");
WebhookEvent ev;
const Json* id_f = doc.find("id");
const Json* type_f = doc.find("type");
const Json* created = doc.find("created_at");
const Json* data = doc.find("data");
const Json* object = doc.find("object");
if (!id_f || !id_f->is_string() || id_f->as_string().empty()) Validate::fail("event has no id");
if (!type_f || !type_f->is_string() || type_f->as_string().empty()) Validate::fail("event has no type");
if (!created || !created->is_number()) Validate::fail("event has no created_at");
if (!data || !data->is_object()) Validate::fail("event has no data object");
if (object && (!object->is_string() || object->as_string() != "event"))
Validate::fail("event object is not \"event\"");
ev.id = id_f->as_string();
ev.type = type_f->as_string();
ev.created_at = static_cast<std::int64_t>(created->as_int());
ev.data = *data;
if (const WebhookEventSpec* spec = WebhookEvents::find(ev.type)) {
ev.known = true;
std::string list = spec->required_data;
std::size_t from = 0;
while (from < list.size()) {
std::size_t comma = list.find(',', from);
std::string field = list.substr(from, comma == std::string::npos ? std::string::npos : comma - from);
if (!field.empty() && !data->find(field)) ev.missing_data_fields.push_back(field);
if (comma == std::string::npos) break;
from = comma + 1;
}
}
return ev;
}
} // namespace molo::openai::admin
+64
View File
@@ -0,0 +1,64 @@
#pragma once
// Webhook event catalog and envelope.
//
// OpenAI delivers `{id, object:"event", created_at, type, data}` to the
// endpoint URL. `WebhookEvents::sent()` lists every event type the OpenAPI
// document declares a payload for (its top-level `webhooks` map);
// `subscribable()` lists the types an endpoint may subscribe to
// (`ProjectEventTypeEnum`, used by the webhook endpoint calls). The two sets
// differ: the spec has payloads for events it does not let endpoints select
// and selectable events with no declared payload (video.*).
#include <cstddef>
#include <cstdint>
#include <string>
#include <vector>
#include "clients/body/json.h"
namespace molo::openai::admin {
struct WebhookEventSpec {
const char* type; // "response.completed"
const char* spec_name; // key in the spec's `webhooks` map
const char* data_fields; // comma list: properties of `data`
const char* required_data; // comma list: required properties of `data`
};
class WebhookEvents {
public:
static std::size_t count();
static const WebhookEventSpec& at(std::size_t index);
static const WebhookEventSpec* find(const std::string& type);
static const std::vector<std::string>& sent();
static const std::vector<std::string>& subscribable();
static bool is_subscribable(const std::string& type);
};
// A parsed delivery body. `known` is false for a type this build has no
// payload description for (accepted, flagged; never an error: OpenAI adds
// event types over time).
struct WebhookEvent {
std::string id;
std::string type;
std::int64_t created_at = 0;
clients::body::Json data;
bool known = false;
std::vector<std::string> missing_data_fields; // required data fields absent
// "response.completed" -> "response"
std::string family() const;
// `data.id` when present (resource id the event is about), else "".
std::string resource_id() const;
clients::body::Json to_json() const;
};
class WebhookEnvelope {
public:
// Throws ApiError::invalid unless the body is an event object with id,
// type, integer created_at and an object `data`. Body capped.
static WebhookEvent parse(const std::string& body);
};
} // namespace molo::openai::admin
+243
View File
@@ -0,0 +1,243 @@
#include "openai/admin/webhooks.h"
#include <algorithm>
#include <cctype>
#include <chrono>
#include "llm/error.h"
#include "openai/admin/caps.h"
#include "openai/admin/validate.h"
#include "security/crypto/Base64.h"
#include "security/crypto/Hmac.h"
#include "security/crypto/SecureRandom.h"
namespace molo::openai::admin {
namespace crypto = security::crypto;
namespace {
constexpr std::size_t kFailureCount = 11;
std::array<std::atomic<std::uint64_t>, kFailureCount> g_failures{};
std::atomic<std::uint64_t> g_accepted{0};
std::string lower(std::string s) {
std::transform(s.begin(), s.end(), s.begin(), [](unsigned char c) { return std::tolower(c); });
return s;
}
[[noreturn]] void bad_secret(const std::string& why) {
Validate::fail("webhook secret unusable: " + why);
}
std::string decode_secret(const std::string& secret) {
if (secret.empty() || secret.size() > AdminCaps::kMaxSecretChars) bad_secret("empty or too long");
static const std::string kPrefix = "whsec_";
if (secret.rfind(kPrefix, 0) != 0) return secret; // raw key bytes, as the SDKs allow
const std::string encoded = secret.substr(kPrefix.size());
std::string decoded;
if (!crypto::Base64::decode(encoded, decoded)) bad_secret("not valid base64");
if (crypto::Base64::encode(decoded) != encoded) bad_secret("base64 is not canonical");
if (decoded.size() < AdminCaps::kMinSecretBytes) bad_secret("decoded key is under 24 bytes");
return decoded;
}
} // namespace
const char* webhook_failure_name(WebhookFailure f) {
switch (f) {
case WebhookFailure::kNone: return "none";
case WebhookFailure::kBadSecret: return "bad_secret";
case WebhookFailure::kBodyTooLarge: return "body_too_large";
case WebhookFailure::kMissingId: return "missing_webhook_id";
case WebhookFailure::kMissingTimestamp: return "missing_webhook_timestamp";
case WebhookFailure::kMissingSignature: return "missing_webhook_signature";
case WebhookFailure::kBadTimestamp: return "bad_timestamp";
case WebhookFailure::kTooOld: return "timestamp_too_old";
case WebhookFailure::kTooNew: return "timestamp_too_new";
case WebhookFailure::kBadSignatureHeader: return "bad_signature_header";
case WebhookFailure::kMismatch: return "signature_mismatch";
}
return "unknown";
}
WebhookHeaders WebhookHeaders::from(const std::map<std::string, std::string>& headers) {
WebhookHeaders out;
for (const auto& [name, value] : headers) {
const std::string n = lower(name);
if (n == "webhook-id") out.id = value;
else if (n == "webhook-timestamp") out.timestamp = value;
else if (n == "webhook-signature") out.signature = value;
}
return out;
}
void WebhookCounters::count(WebhookFailure failure) {
g_failures[static_cast<std::size_t>(failure)].fetch_add(1, std::memory_order_relaxed);
}
std::uint64_t WebhookCounters::value(WebhookFailure failure) {
return g_failures[static_cast<std::size_t>(failure)].load(std::memory_order_relaxed);
}
std::uint64_t WebhookCounters::accepted() { return g_accepted.load(std::memory_order_relaxed); }
void WebhookCounters::count_accepted() { g_accepted.fetch_add(1, std::memory_order_relaxed); }
std::map<std::string, std::uint64_t> WebhookCounters::snapshot() {
std::map<std::string, std::uint64_t> out;
out["accepted"] = accepted();
for (std::size_t i = 1; i < kFailureCount; ++i)
out[webhook_failure_name(static_cast<WebhookFailure>(i))] = value(static_cast<WebhookFailure>(i));
return out;
}
WebhookVerifier::WebhookVerifier(const std::string& secret, std::int64_t tolerance_seconds)
: key_(decode_secret(secret)), tolerance_(tolerance_seconds) {
Validate::range("tolerance_seconds", tolerance_seconds, 0, AdminCaps::kMaxToleranceSeconds);
}
WebhookVerifier::~WebhookVerifier() { crypto::SecureRandom::zeroize(key_); }
std::int64_t WebhookVerifier::system_now() {
return std::chrono::duration_cast<std::chrono::seconds>(
std::chrono::system_clock::now().time_since_epoch())
.count();
}
std::string WebhookVerifier::sign(const std::string& webhook_id, const std::string& timestamp,
const std::string& body) const {
const std::string signed_payload = webhook_id + "." + timestamp + "." + body;
const auto mac = crypto::Hmac::sha256(key_, signed_payload);
return "v1," + crypto::Base64::encode(mac.data(), mac.size());
}
VerifyResult WebhookVerifier::verify(const std::string& body, const WebhookHeaders& h) const {
return verify(body, h, system_now());
}
VerifyResult WebhookVerifier::verify(const std::string& body, const WebhookHeaders& h,
std::int64_t now) const {
auto reject = [](WebhookFailure f, const std::string& why) {
WebhookCounters::count(f);
VerifyResult r;
r.failure = f;
r.reason = why;
return r;
};
if (body.size() > AdminCaps::kMaxWebhookBodyBytes)
return reject(WebhookFailure::kBodyTooLarge, "body is over the byte cap");
if (h.id.empty() || h.id.size() > 256)
return reject(WebhookFailure::kMissingId, "missing webhook-id header");
if (h.timestamp.empty())
return reject(WebhookFailure::kMissingTimestamp, "missing webhook-timestamp header");
if (h.signature.empty())
return reject(WebhookFailure::kMissingSignature, "missing webhook-signature header");
if (h.signature.size() > AdminCaps::kMaxWebhookHeaderChars)
return reject(WebhookFailure::kBadSignatureHeader, "webhook-signature header is too long");
if (h.timestamp.size() > 12 ||
!std::all_of(h.timestamp.begin(), h.timestamp.end(),
[](unsigned char c) { return std::isdigit(c) != 0; }))
return reject(WebhookFailure::kBadTimestamp, "webhook-timestamp is not unix seconds");
const std::int64_t ts = std::stoll(h.timestamp);
if (now - ts > tolerance_) return reject(WebhookFailure::kTooOld, "timestamp is outside the tolerance (old)");
if (ts - now > tolerance_) return reject(WebhookFailure::kTooNew, "timestamp is outside the tolerance (future)");
// Candidate signatures: space separated "v1,<base64>" entries.
std::vector<std::string> candidates;
std::size_t pos = 0;
while (pos < h.signature.size()) {
while (pos < h.signature.size() && std::isspace(static_cast<unsigned char>(h.signature[pos]))) ++pos;
std::size_t end = pos;
while (end < h.signature.size() && !std::isspace(static_cast<unsigned char>(h.signature[end]))) ++end;
if (end > pos) {
const std::string part = h.signature.substr(pos, end - pos);
if (part.rfind("v1,", 0) == 0) candidates.push_back(part.substr(3));
}
pos = end;
}
if (candidates.empty())
return reject(WebhookFailure::kBadSignatureHeader, "no v1 signature in webhook-signature");
if (candidates.size() > AdminCaps::kMaxWebhookSignatures)
return reject(WebhookFailure::kBadSignatureHeader, "too many signatures in webhook-signature");
const std::string signed_payload = h.id + "." + h.timestamp + "." + body;
const auto expected = crypto::Hmac::sha256(key_, signed_payload);
bool match = false;
for (const std::string& c : candidates) {
std::string raw;
if (!crypto::Base64::decode(c, raw) || raw.size() != expected.size()) continue;
match |= crypto::SecureRandom::constant_time_equal(
reinterpret_cast<const std::uint8_t*>(raw.data()), expected.data(), expected.size());
}
if (!match) return reject(WebhookFailure::kMismatch, "signature does not match");
WebhookCounters::count_accepted();
VerifyResult ok;
ok.ok = true;
return ok;
}
void WebhookVerifier::require(const std::string& body, const WebhookHeaders& h,
std::int64_t now) const {
const VerifyResult r = verify(body, h, now);
if (!r.ok) throw llm::ApiError("openai", 401, "INVALID_SIGNATURE", r.reason);
}
WebhookEvent WebhookVerifier::unwrap(const std::string& body, const WebhookHeaders& h,
std::int64_t now) const {
require(body, h, now);
return WebhookEnvelope::parse(body);
}
// ---- endpoint management ----
AdminService::Json WebhookEndpoints::list(std::optional<int> limit, const std::string& after) {
Query q;
if (limit) {
Validate::range("limit", *limit, 1, AdminCaps::kMaxPageLimit);
q.set_int("limit", *limit);
}
if (!after.empty()) q.set("after", after);
return execute(Call::kWebhookEndpointsList, {}, q);
}
AdminService::Json WebhookEndpoints::get(const std::string& endpoint_id) {
return execute(Call::kWebhookEndpointsGet, {endpoint_id});
}
AdminService::Json WebhookEndpoints::create(const WebhookEndpointSpec& spec) {
Json body = spec.to_json(true);
return execute(Call::kWebhookEndpointsCreate, {}, {}, &body);
}
AdminService::Json WebhookEndpoints::update(const std::string& endpoint_id,
const WebhookEndpointSpec& spec) {
Json body = spec.to_json(false);
return execute(Call::kWebhookEndpointsUpdate, {endpoint_id}, {}, &body);
}
AdminService::Json WebhookEndpoints::destroy(const std::string& endpoint_id, bool confirm) {
return execute(Call::kWebhookEndpointsDelete, {endpoint_id}, {}, nullptr, confirm);
}
AdminService::Json WebhookEndpoints::rotate_secret(const std::string& endpoint_id,
bool keep_old_secret_for_24_hours,
bool confirm) {
Json body = Json::object();
body.set("keep_old_secret_active_for_24_hours", Json(keep_old_secret_for_24_hours));
return execute(Call::kWebhookEndpointsRotateSecret, {endpoint_id}, {}, &body, confirm);
}
AdminService::Json WebhookEndpoints::test(const std::string& endpoint_id,
const std::string& event_type) {
if (!WebhookEvents::is_subscribable(event_type))
Validate::fail("event type " + event_type + " cannot be tested");
Json body = Json::object();
body.set("event_type", Json(event_type));
return execute(Call::kWebhookEndpointsTest, {endpoint_id}, {}, &body);
}
AdminService::Json WebhookEndpoints::event_types() {
return execute(Call::kWebhookEventTypesList);
}
} // namespace molo::openai::admin
+119
View File
@@ -0,0 +1,119 @@
#pragma once
// Webhooks: signature verification (Standard Webhooks, HMAC-SHA256, as
// OpenAI documents and its official SDKs implement) and endpoint management.
//
// Verification algorithm (read from openai-go webhooks/webhook_helpers.go and
// webhook_secret.go, cross-checked with the Standard Webhooks spec):
// headers webhook-id, webhook-timestamp (unix seconds), webhook-signature
// signed "<webhook-id>.<webhook-timestamp>.<raw body>"
// key secret "whsec_<base64>" -> decoded bytes (>= 24 bytes, canonical
// base64); a secret without the prefix is used as raw bytes
// signature base64(HMAC-SHA256(key, signed)); the header holds one or more
// space separated "v1,<base64>" entries, any match is enough
// tolerance |now - timestamp| <= tolerance (default 300 s)
// Comparison is constant time (SecureRandom::constant_time_equal). Stricter
// than openai-go in one way: an entry without the "v1," prefix is ignored, and
// entries of other versions (v1a, ...) are skipped, as the Standard Webhooks
// spec says. The raw request body must be passed byte for byte.
#include <array>
#include <atomic>
#include <cstdint>
#include <map>
#include <string>
#include <vector>
#include "openai/admin/admin_service.h"
#include "openai/admin/requests.h"
#include "openai/admin/webhook_events.h"
namespace molo::openai::admin {
enum class WebhookFailure {
kNone, kBadSecret, kBodyTooLarge, kMissingId, kMissingTimestamp, kMissingSignature,
kBadTimestamp, kTooOld, kTooNew, kBadSignatureHeader, kMismatch
};
const char* webhook_failure_name(WebhookFailure failure);
// The three delivery headers; build with `from` (case-insensitive names).
struct WebhookHeaders {
std::string id; // webhook-id
std::string timestamp; // webhook-timestamp
std::string signature; // webhook-signature
static WebhookHeaders from(const std::map<std::string, std::string>& headers);
};
struct VerifyResult {
bool ok = false;
WebhookFailure failure = WebhookFailure::kNone;
std::string reason; // human readable, never contains the secret or the body
};
// Process-wide counters of rejected deliveries by reason (loud skips).
class WebhookCounters {
public:
static void count(WebhookFailure failure);
static std::uint64_t value(WebhookFailure failure);
static std::uint64_t accepted();
static void count_accepted();
static std::map<std::string, std::uint64_t> snapshot();
};
class WebhookVerifier {
public:
// Throws ApiError::invalid on an unusable secret (never echoes it).
explicit WebhookVerifier(const std::string& secret,
std::int64_t tolerance_seconds = 300);
~WebhookVerifier();
WebhookVerifier(const WebhookVerifier&) = default;
WebhookVerifier& operator=(const WebhookVerifier&) = default;
std::int64_t tolerance_seconds() const { return tolerance_; }
// Never throws; counts every rejection.
VerifyResult verify(const std::string& body, const WebhookHeaders& headers,
std::int64_t now_unix) const;
VerifyResult verify(const std::string& body, const WebhookHeaders& headers) const;
// Throws ApiError 401 INVALID_SIGNATURE on a failed verification.
void require(const std::string& body, const WebhookHeaders& headers,
std::int64_t now_unix) const;
// Verify, then parse the envelope. The body is never parsed before it verifies.
WebhookEvent unwrap(const std::string& body, const WebhookHeaders& headers,
std::int64_t now_unix) const;
// "v1,<base64>" for a delivery; used by tests and by senders of test events.
std::string sign(const std::string& webhook_id, const std::string& timestamp,
const std::string& body) const;
static std::int64_t system_now();
private:
std::string key_;
std::int64_t tolerance_;
};
// /webhook_endpoints. These calls use the regular project API key
// (OPENAI_API_KEY); an admin key is refused by ProjectApiClient.
class WebhookEndpoints : public AdminService {
public:
explicit WebhookEndpoints(std::shared_ptr<ProjectApiClient> client)
: AdminService(std::move(client)) {}
Json list(std::optional<int> limit = std::nullopt, const std::string& after = "");
Json get(const std::string& endpoint_id);
// The answer carries the signing secret once.
Json create(const WebhookEndpointSpec& spec);
Json update(const std::string& endpoint_id, const WebhookEndpointSpec& spec);
Json destroy(const std::string& endpoint_id, bool confirm);
// Replaces the signing secret (new secret returned once). Needs confirm: the
// old secret stops verifying unless keep_old_secret_for_24_hours.
Json rotate_secret(const std::string& endpoint_id, bool keep_old_secret_for_24_hours,
bool confirm);
// Makes OpenAI deliver a test event of that type to the endpoint URL.
Json test(const std::string& endpoint_id, const std::string& event_type);
Json event_types();
};
} // namespace molo::openai::admin