platform:manage you can also change it as the Console does: set a capability’s chain, turn a capability off, set a provider’s options, enable or disable a provider, add a provider record, and bind an org unit to a provider. Options that repoint a provider at another host stay Console-only.
Who can read it
The five catalog reads (listCapabilities, getCapability, listCapabilityAuditEvents, listProviders, getProvider) require grants:read, policies:read and audit:read (the Governance reader preset). Capabilities and providers are deployment configuration, not tenant data, so the three permissions must be held at the deployment root: a platform grant, or a grant at the root org unit. A credential granted only at a tenant org unit gets 403 permission_denied with error.requiredPermission, and the refusal is recorded like any other permission denial. Migrated API keys carry a root-org-unit grant and are unaffected. listProviderAuditEvents requires audit:read alone, at the platform scope; getCapabilityBindingReadiness requires credentials:read at the org unit it names (a grant at the platform, an ancestor or the unit).
Resource shapes
Credential health
CredentialHealth describes one connection target (<vendor>/<connection>), such as openai/inference:
Health is credential resolution and last verification only. There is no runtime health probe, so an
ok verification is not a promise that the next call succeeds. An invalid or unreachable status is the signal that a credential needs attention.
A platform API key or a Personal key administers Credentials through the Connections administration routes; an External App is refused with 403. POST /api/v3/connection-credentials/provision creates a vendor connection’s Credential, or rotates it in place, with credentials:write. POST /api/v3/connection-credentials/{credentialId}/approve approves a pending one with credentials:approve. POST /api/v3/connection-credentials/{credentialId}/revoke revokes one and POST /api/v3/connection-credentials/{credentialId}/set-sharing seals or shares one, each with credentials:manage. Each of these needs its permission at platform scope. The Capabilities reads answer the handoff, never the credential identity or secret.
What is never returned
Credential values, credential ids, credential scopes and names, field names, env-var names, deployment and per-binding option values, provider icons and custom renderer slugs are not on the wire. Capability and provider audit events omit the actor and the change detail, which stay in the Console.Operations
Reads:GET /api/v3/capabilities— listCapabilities — every capability domainGET /api/v3/capabilities/{domain}— getCapability — one domain with provider healthGET /api/v3/capabilities/{domain}/audit-events?limit=— listCapabilityAuditEvents — a domain’s recent changesGET /api/v3/providers— listProviders — the provider catalogGET /api/v3/providers/{providerKey}— getProvider — one provider with credential healthGET /api/v3/providers/{providerKey}/audit-events?limit=— listProviderAuditEvents — a provider’s recent changes (audit:readat the platform scope)GET /api/v3/capabilities/{domain}/binding-readiness?orgUnitId=— getCapabilityBindingReadiness — a capability’s provider binding for one org unit (credentials:readat the unit)
platform:manage, each idempotent with an Idempotency-Key):
POST /api/v3/capabilities/{domain}/set-chain— setCapabilityChain — a domain’s provider chain and binding optionsPOST /api/v3/capabilities/{domain}/disable— disableCapability — turn a domain offPOST /api/v3/providers/{providerKey}/set-options— setProviderOptions — a provider’s global optionsPOST /api/v3/providers/{providerKey}/enable— enableProvider — a provider and its chained records onPOST /api/v3/providers/{providerKey}/disable— disableProvider — a provider and its records offPOST /api/v3/provider-records— createProviderRecord — a protocol-generic provider recordPOST /api/v3/capabilities/{domain}/bind-organization— bindCapabilityOrganization — an org unit’s provider binding (platform:manageat the unit)
meta.hasMore is false and there is no cursor. A missing domain or key is 400 bad_request; an unknown one is 404 resource_missing.
Common workflows
Related
- Governance — the other reads that require
grants:read,policies:readandaudit:read - MCP server —
forge_call_operationwith operationIdlistCapabilities,getCapability,listCapabilityAuditEvents,listProvidersorgetProvider

