docs(clients): document the activation page of every Google API and each vendor key page

Adds molo::google::apis (api_catalog) as the code source of truth,
src/google/APIS.md, a Required APIs section per module SPEC, and the
vendor key consoles in src/llm/SPEC.md. Placeholder project example-214512124.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-25 08:02:50 +01:00
co-authored by Claude Sonnet 5.5
parent 865ce89784
commit 438e737ffb
16 changed files with 349 additions and 0 deletions
+3
View File
@@ -88,6 +88,9 @@ minted for the OAuth-only APIs).
### Live checks
Which Google APIs to enable (with console links) is in `src/google/APIS.md`;
where to create each vendor key is in `src/llm/SPEC.md` section 5.
Hermetic tests never touch the network and ignore `.env.json.local`
(`MOLO_ENV_FILES=off`). Live checks are opt-in:
+87
View File
@@ -0,0 +1,87 @@
# Google Cloud APIs: what to enable and where
Every Google API this build calls, with the page that enables it. A disabled
API answers `403 PERMISSION_DENIED` with reason `SERVICE_DISABLED`; the
"Enable" link below is the same activation page Google puts in that error.
The code mirror of this table is `api_catalog.h/.cpp` (`molo::google::apis`);
`tests/src/google/test_api_catalog.cpp` pins the URL format.
Placeholder project in this file: `example-214512124` (a valid project id: 6-30 chars,
lowercase letters, digits, hyphens, starts with a letter). Replace it with the
value of `GOOGLE_CLOUD_PROJECT`. The service names and titles were read from
Service Usage (`GET serviceusage.googleapis.com/v1/projects/<id>/services/<service>`).
Enable page pattern:
`https://console.developers.google.com/apis/api/<service>/overview?project=<id>`
Fast path for all of them:
```sh
gcloud services enable \
aiplatform.googleapis.com \
generativelanguage.googleapis.com \
texttospeech.googleapis.com \
speech.googleapis.com \
modelarmor.googleapis.com \
securitycenter.googleapis.com \
agentregistry.googleapis.com \
networkservices.googleapis.com \
networksecurity.googleapis.com \
iamcredentials.googleapis.com \
cloudtrace.googleapis.com \
logging.googleapis.com \
--project=example-214512124
```
## APIs
| API | Service | Used by | Enable |
|---|---|---|---|
| Agent Platform API (Vertex AI) | `aiplatform.googleapis.com` | models, runtime, sessions, sandbox, optimize, adk, live, voice (vertex backend) | [enable](https://console.developers.google.com/apis/api/aiplatform.googleapis.com/overview?project=example-214512124) |
| Gemini API | `generativelanguage.googleapis.com` | voice (gemini backend), live (API key) | [enable](https://console.developers.google.com/apis/api/generativelanguage.googleapis.com/overview?project=example-214512124) |
| Cloud Text-to-Speech API | `texttospeech.googleapis.com` | voice (cloud backend) | [enable](https://console.developers.google.com/apis/api/texttospeech.googleapis.com/overview?project=example-214512124) |
| Cloud Speech-to-Text API | `speech.googleapis.com` | voice (cloud backend) | [enable](https://console.developers.google.com/apis/api/speech.googleapis.com/overview?project=example-214512124) |
| Model Armor API | `modelarmor.googleapis.com` | armor | [enable](https://console.developers.google.com/apis/api/modelarmor.googleapis.com/overview?project=example-214512124) |
| Security Command Center API | `securitycenter.googleapis.com` | armor | [enable](https://console.developers.google.com/apis/api/securitycenter.googleapis.com/overview?project=example-214512124) |
| Agent Registry API | `agentregistry.googleapis.com` | registry | [enable](https://console.developers.google.com/apis/api/agentregistry.googleapis.com/overview?project=example-214512124) |
| Network Services API | `networkservices.googleapis.com` | registry | [enable](https://console.developers.google.com/apis/api/networkservices.googleapis.com/overview?project=example-214512124) |
| Network Security API | `networksecurity.googleapis.com` | registry | [enable](https://console.developers.google.com/apis/api/networksecurity.googleapis.com/overview?project=example-214512124) |
| IAM Service Account Credentials API | `iamcredentials.googleapis.com` | sandbox (data plane JWT) | [enable](https://console.developers.google.com/apis/api/iamcredentials.googleapis.com/overview?project=example-214512124) |
| Cloud Trace API | `cloudtrace.googleapis.com` | optimize | [enable](https://console.developers.google.com/apis/api/cloudtrace.googleapis.com/overview?project=example-214512124) |
| Cloud Logging API | `logging.googleapis.com` | optimize | [enable](https://console.developers.google.com/apis/api/logging.googleapis.com/overview?project=example-214512124) |
Extra steps beyond enabling:
- Security Command Center API: Enabling the API is not enough: Security Command Center must also be activated for the organization (https://console.cloud.google.com/security/command-center). Activation can need an organization-level role and may cost money.
- IAM Service Account Credentials API: The service account also needs `roles/iam.serviceAccountTokenCreator` on the account it signs for.
## Credential pages
| What | Page |
|---|---|
| API keys (`GOOGLE_API_KEY`) | https://console.cloud.google.com/apis/credentials?project=example-214512124 |
| Service accounts and their keys (`GOOGLE_APPLICATION_CREDENTIALS`) | https://console.cloud.google.com/iam-admin/serviceaccounts?project=example-214512124 |
Express-mode (Vertex) keys start with `AQ.` and work only on the express
endpoints; every other API here needs the service-account OAuth token.
## Not an enable step
- `oauth2.googleapis.com` (service-account token exchange) and
`www.googleapis.com/auth/cloud-platform` (the OAuth scope) need no enabling.
- `*.rep.googleapis.com` hosts are regional endpoints of an API above, not
separate services.
## Verifying
`make google-live` runs the live checks; a module whose API is off prints
`API NOT ENABLED in this project: <service>` and does not fail silently. To
read the state of one service directly:
```sh
curl -s -H "Authorization: Bearer $(build/google/sa-token)" \
https://serviceusage.googleapis.com/v1/projects/example-214512124/services/agentregistry.googleapis.com
```
(`state` is `ENABLED` or `DISABLED`; the service account needs permission to
read Service Usage.)
+1
View File
@@ -19,6 +19,7 @@ client, credentials, errors, or caps.
| `credentials.h/.cpp` | `Credentials`: API key and OAuth bearer providers, env loader |
| `service_account.h/.cpp` | `ServiceAccountKey`, `JwtSigner` (RS256), `ServiceAccountAuth` (self-refreshing bearer) |
| `endpoints.h/.cpp` | `ServiceEndpoint` plus the catalog of known services |
| `api_catalog.h/.cpp` | `apis`: every Google API service the code calls, its console title and activation URL (docs mirror: `APIS.md`) |
| `client.h/.cpp` | `GoogleClient`: auth, JSON in/out, error mapping, over any `clients::Transport` |
| `service.h/.cpp` | `Service` base class: holds client plus endpoint, one `call()` |
| `text_to_speech.h/.cpp` | `TextToSpeech::synthesize`, `voices` |
+7
View File
@@ -251,3 +251,10 @@ loud SKIP otherwise):
- Agent Config: callbacks, `generate_content_config`, schemas and
`include_contents` are rejected, not implemented; `config_path` /
`code` sub-agent references are rejected.
## Required APIs
Enable these on the project (placeholder project `example-214512124`; full list and a one-line `gcloud` command in `src/google/APIS.md`). A disabled API answers 403 `SERVICE_DISABLED`.
- `aiplatform.googleapis.com`: https://console.developers.google.com/apis/api/aiplatform.googleapis.com/overview?project=example-214512124 (the DirectModel adapter calls Gemini)
+78
View File
@@ -0,0 +1,78 @@
#include "google/api_catalog.h"
#include "google/errors.h"
namespace molo::google::apis {
const std::vector<ApiInfo>& all() {
static const std::vector<ApiInfo> kApis = {
{"aiplatform.googleapis.com", "Agent Platform API (Vertex AI)",
"models, runtime, sessions, sandbox, optimize, adk, live, voice (vertex backend)", ""},
{"generativelanguage.googleapis.com", "Gemini API",
"voice (gemini backend), live (API key)", ""},
{"texttospeech.googleapis.com", "Cloud Text-to-Speech API",
"voice (cloud backend)", ""},
{"speech.googleapis.com", "Cloud Speech-to-Text API",
"voice (cloud backend)", ""},
{"modelarmor.googleapis.com", "Model Armor API", "armor", ""},
{"securitycenter.googleapis.com", "Security Command Center API", "armor",
"Enabling the API is not enough: Security Command Center must also be "
"activated for the organization "
"(https://console.cloud.google.com/security/command-center)."},
{"agentregistry.googleapis.com", "Agent Registry API", "registry", ""},
{"networkservices.googleapis.com", "Network Services API", "registry", ""},
{"networksecurity.googleapis.com", "Network Security API", "registry", ""},
{"iamcredentials.googleapis.com", "IAM Service Account Credentials API",
"sandbox (data plane JWT)",
"The service account also needs roles/iam.serviceAccountTokenCreator "
"on the account it signs for."},
{"cloudtrace.googleapis.com", "Cloud Trace API", "optimize", ""},
{"logging.googleapis.com", "Cloud Logging API", "optimize", ""},
};
return kApis;
}
const ApiInfo* find(const std::string& service) {
for (const ApiInfo& api : all())
if (api.service == service) return &api;
return nullptr;
}
bool valid_project(const std::string& project) {
if (project.size() < 6 || project.size() > 30) return false;
if (project.front() < 'a' || project.front() > 'z') return false;
if (project.back() == '-') return false;
for (char c : project)
if (!((c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || c == '-')) return false;
return true;
}
namespace {
void require(const std::string& service, const std::string& project) {
if (!find(service)) throw GoogleError::invalid("unknown Google API service: " + service);
if (!valid_project(project)) throw GoogleError::invalid("invalid project id: " + project);
}
} // namespace
std::string enable_url(const std::string& service, const std::string& project) {
require(service, project);
return "https://console.developers.google.com/apis/api/" + service +
"/overview?project=" + project;
}
std::string enable_command(const std::string& service, const std::string& project) {
require(service, project);
return "gcloud services enable " + service + " --project=" + project;
}
std::string api_keys_url(const std::string& project) {
if (!valid_project(project)) throw GoogleError::invalid("invalid project id: " + project);
return "https://console.cloud.google.com/apis/credentials?project=" + project;
}
std::string service_accounts_url(const std::string& project) {
if (!valid_project(project)) throw GoogleError::invalid("invalid project id: " + project);
return "https://console.cloud.google.com/iam-admin/serviceaccounts?project=" + project;
}
} // namespace molo::google::apis
+42
View File
@@ -0,0 +1,42 @@
#pragma once
// Every Google API service this build calls, with the console page that
// enables it. A disabled API answers 403 SERVICE_DISABLED; the URL below is
// the same activation page Google puts in that error.
// Add a row in api_catalog.cpp when a module starts calling a new service.
#include <string>
#include <vector>
namespace molo::google::apis {
// Placeholder project used in docs and examples. Valid project id format:
// 6-30 chars, lowercase letters, digits and hyphens, starts with a letter.
inline constexpr const char* kExampleProject = "example-214512124";
struct ApiInfo {
std::string service; // "agentregistry.googleapis.com"
std::string title; // Console title, as Service Usage reports it
std::string used_by; // Modules under src/google that call it
std::string note; // Extra activation step beyond enabling, or empty
};
// All known services, fixed order.
const std::vector<ApiInfo>& all();
// Null when the service is not in the catalog.
const ApiInfo* find(const std::string& service);
// True for a valid project id (see kExampleProject).
bool valid_project(const std::string& project);
// https://console.developers.google.com/apis/api/<service>/overview?project=<id>
// Throws GoogleError::invalid for an unknown service or a bad project id.
std::string enable_url(const std::string& service, const std::string& project);
// gcloud services enable <service> --project=<id>
std::string enable_command(const std::string& service, const std::string& project);
// Console pages for credentials, not tied to one API.
std::string api_keys_url(const std::string& project);
std::string service_accounts_url(const std::string& project);
} // namespace molo::google::apis
+8
View File
@@ -256,3 +256,11 @@ Nothing neither Discovery nor docs state:
findings, group, config or admin response was ever seen. Owner: whoever
activates SCC at the organization; tests `google_live_armor.*`.
- Token refresh is the caller's job (foundation gap).
## Required APIs
Enable these on the project (placeholder project `example-214512124`; full list and a one-line `gcloud` command in `src/google/APIS.md`). A disabled API answers 403 `SERVICE_DISABLED`.
- `modelarmor.googleapis.com`: https://console.developers.google.com/apis/api/modelarmor.googleapis.com/overview?project=example-214512124
- `securitycenter.googleapis.com`: https://console.developers.google.com/apis/api/securitycenter.googleapis.com/overview?project=example-214512124 (also needs Security Command Center activated for the organization: https://console.cloud.google.com/security/command-center)
+7
View File
@@ -166,6 +166,13 @@ measured against a local TLS 1.3 server (see Contracts, TLS); there is no
automated test of the real session against a self-signed peer, because it
loads only the system CA store.
## Required APIs
Enable these on the project (placeholder project `example-214512124`; full list and a one-line `gcloud` command in `src/google/APIS.md`). A disabled API answers 403 `SERVICE_DISABLED`.
- `generativelanguage.googleapis.com`: https://console.developers.google.com/apis/api/generativelanguage.googleapis.com/overview?project=example-214512124 (API key path)
- `aiplatform.googleapis.com`: https://console.developers.google.com/apis/api/aiplatform.googleapis.com/overview?project=example-214512124 (Vertex path)
## Sources
- https://ai.google.dev/api/live (WebSocket API reference: messages, fields)
+8
View File
@@ -283,3 +283,11 @@ response; the empty endpoint list shape; thought signatures on function calls.
Claude `streamRawPredict`) goes through the foundation `StreamDecoder`, which
is outside this module; not verified that it maps to `GoogleError`.
- Token refresh is the caller's job (foundation gap).
## Required APIs
Enable these on the project (placeholder project `example-214512124`; full list and a one-line `gcloud` command in `src/google/APIS.md`). A disabled API answers 403 `SERVICE_DISABLED`.
- `aiplatform.googleapis.com`: https://console.developers.google.com/apis/api/aiplatform.googleapis.com/overview?project=example-214512124
- `generativelanguage.googleapis.com`: https://console.developers.google.com/apis/api/generativelanguage.googleapis.com/overview?project=example-214512124 (only for the AI Studio key path, not express mode)
+8
View File
@@ -220,6 +220,14 @@ These are verified by discovery only.
not Google's. Owner: `simulator.cpp`, `optimizer.cpp`.
- Token refresh is the caller's job (foundation gap).
## Required APIs
Enable these on the project (placeholder project `example-214512124`; full list and a one-line `gcloud` command in `src/google/APIS.md`). A disabled API answers 403 `SERVICE_DISABLED`.
- `aiplatform.googleapis.com`: https://console.developers.google.com/apis/api/aiplatform.googleapis.com/overview?project=example-214512124 (evaluation)
- `cloudtrace.googleapis.com`: https://console.developers.google.com/apis/api/cloudtrace.googleapis.com/overview?project=example-214512124 (traces)
- `logging.googleapis.com`: https://console.developers.google.com/apis/api/logging.googleapis.com/overview?project=example-214512124 (logs)
## Sources
- aiplatform v1 Discovery: https://aiplatform.googleapis.com/$discovery/rest?version=v1
+8
View File
@@ -115,6 +115,14 @@ on bad input) and `/identity/principal` (local, no credential). `/list` takes
`/operations?scope=registry|gateways|policies&id=` (the operation record only). `/approve` and
`/deprecate` read the asset from Google first.
## Required APIs
Enable these on the project (placeholder project `example-214512124`; full list and a one-line `gcloud` command in `src/google/APIS.md`). A disabled API answers 403 `SERVICE_DISABLED`.
- `agentregistry.googleapis.com`: https://console.developers.google.com/apis/api/agentregistry.googleapis.com/overview?project=example-214512124
- `networkservices.googleapis.com`: https://console.developers.google.com/apis/api/networkservices.googleapis.com/overview?project=example-214512124 (agent gateways)
- `networksecurity.googleapis.com`: https://console.developers.google.com/apis/api/networksecurity.googleapis.com/overview?project=example-214512124 (authorization policies)
## Sources
- https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/agent-registry
+6
View File
@@ -110,6 +110,12 @@ validated first (422), then a credential is required (503
`google_not_configured`); destructive actions are dry runs unless
`"confirm":true`; oversize body: 413.
## Required APIs
Enable these on the project (placeholder project `example-214512124`; full list and a one-line `gcloud` command in `src/google/APIS.md`). A disabled API answers 403 `SERVICE_DISABLED`.
- `aiplatform.googleapis.com`: https://console.developers.google.com/apis/api/aiplatform.googleapis.com/overview?project=example-214512124
## Sources
- Discovery documents, fetched 2026-10-24 (revision 20261012 for both):
+8
View File
@@ -373,3 +373,11 @@ for one call (optionally attaching the first page) and closes it; `stream` is
`google_not_configured`; bad input is 422. Tests: `tests/example/agent/sandbox/`
(route tests) and `tests/src/google/sandbox/` (module tests, loopback data
plane in `test_sandbox_dataplane.cpp`).
## Required APIs
Enable these on the project (placeholder project `example-214512124`; full list and a one-line `gcloud` command in `src/google/APIS.md`). A disabled API answers 403 `SERVICE_DISABLED`.
- `aiplatform.googleapis.com`: https://console.developers.google.com/apis/api/aiplatform.googleapis.com/overview?project=example-214512124
- `iamcredentials.googleapis.com`: https://console.developers.google.com/apis/api/iamcredentials.googleapis.com/overview?project=example-214512124 (signs the data plane JWT; the service account also needs roles/iam.serviceAccountTokenCreator)
+7
View File
@@ -207,3 +207,10 @@ Neither discovery nor the docs pages read state these; they are inferred:
feature; test `sessions_live.operations_and_serving_profiles_reads`.
- Session and memory `labels` / `metadata` filters beyond a passthrough string.
- Token refresh is the caller's job (foundation gap).
## Required APIs
Enable these on the project (placeholder project `example-214512124`; full list and a one-line `gcloud` command in `src/google/APIS.md`). A disabled API answers 403 `SERVICE_DISABLED`.
- `aiplatform.googleapis.com`: https://console.developers.google.com/apis/api/aiplatform.googleapis.com/overview?project=example-214512124
+24
View File
@@ -59,3 +59,27 @@ Reported by the vendor modules, owner `src/llm`:
(Anthropic redacted thinking, Meta encrypted reasoning, OpenRouter
`reasoning_details`); vendor models carry them on the side.
- `Url` percent-encodes `[` and `]` in query names.
## 5. Credentials and consoles
Where to create each key. Pages marked (read) were fetched and answered 200 or
redirected to sign-in; (docs) are linked from the vendor's own documentation;
(unverified) are the vendor's usual path, but the page blocked automated
fetches, so open it by hand.
| Vendor | Env var | Page |
|---|---|---|
| xAI | `XAI_API_KEY` | https://console.x.ai/team/default/api-keys (docs) |
| xAI | `XAI_MANAGEMENT_KEY` | https://console.x.ai (unverified: the exact page is not named in the docs read) |
| Anthropic | `ANTHROPIC_API_KEY` | https://platform.claude.com/settings/keys (read) |
| Anthropic | `ANTHROPIC_ADMIN_KEY` | https://platform.claude.com/settings/admin-keys (read) |
| Meta Model API | `META_API_KEY` / `MODEL_API_KEY` | https://dev.meta.ai/ , "API keys" tab (docs: https://dev.meta.ai/docs/authentication) |
| DeepSeek | `DEEPSEEK_API_KEY` | https://platform.deepseek.com/api_keys (docs) |
| OpenAI | `OPENAI_API_KEY` | https://platform.openai.com/api-keys (docs) |
| OpenAI | `OPENAI_ADMIN_KEY` | https://platform.openai.com/settings/organization/admin-keys (unverified) |
| OpenRouter | `OPENROUTER_API_KEY` | https://openrouter.ai/keys (read) |
| OpenRouter | `OPENROUTER_MANAGEMENT_KEY` | https://openrouter.ai/settings/management-keys (read) |
Anthropic's old host `console.anthropic.com` redirects to `platform.claude.com`.
Google's keys and the APIs to enable live in `src/google/APIS.md`.
+47
View File
@@ -0,0 +1,47 @@
// The API catalog: every service has a well-formed activation URL.
#include <set>
#include "framework.h"
#include "google/api_catalog.h"
#include "google/errors.h"
using namespace molo::google;
TEST(api_catalog, services_unique_and_well_formed) {
std::set<std::string> seen;
const std::string suffix = ".googleapis.com";
for (const auto& api : apis::all()) {
ASSERT_TRUE(seen.insert(api.service).second);
ASSERT_TRUE(api.service.size() > suffix.size());
ASSERT_EQ(api.service.substr(api.service.size() - suffix.size()), suffix);
ASSERT_FALSE(api.title.empty());
ASSERT_FALSE(api.used_by.empty());
}
ASSERT_TRUE(apis::all().size() >= 12u);
}
TEST(api_catalog, enable_url_matches_google_activation_page) {
ASSERT_EQ(apis::enable_url("agentregistry.googleapis.com", apis::kExampleProject),
"https://console.developers.google.com/apis/api/agentregistry.googleapis.com/"
"overview?project=example-214512124");
ASSERT_EQ(apis::enable_command("iamcredentials.googleapis.com", apis::kExampleProject),
"gcloud services enable iamcredentials.googleapis.com --project=example-214512124");
}
TEST(api_catalog, example_project_valid_and_bad_ids_rejected) {
ASSERT_TRUE(apis::valid_project(apis::kExampleProject));
ASSERT_FALSE(apis::valid_project("Short"));
ASSERT_FALSE(apis::valid_project("1starts-with-digit"));
ASSERT_FALSE(apis::valid_project("ends-with-hyphen-"));
ASSERT_FALSE(apis::valid_project("has_underscore"));
ASSERT_FALSE(apis::valid_project(std::string(31, 'a')));
ASSERT_THROW(apis::enable_url("agentregistry.googleapis.com", "bad id"), GoogleError);
ASSERT_THROW(apis::enable_url("nope.googleapis.com", apis::kExampleProject), GoogleError);
}
TEST(api_catalog, credential_pages) {
ASSERT_EQ(apis::api_keys_url(apis::kExampleProject),
"https://console.cloud.google.com/apis/credentials?project=example-214512124");
ASSERT_EQ(apis::service_accounts_url(apis::kExampleProject),
"https://console.cloud.google.com/iam-admin/serviceaccounts?project=example-214512124");
}