Admin API
Reference
Admin API
Section titled “Admin API”Generated source hash: sha256:22a78e07be1689f1de50d76f80bd976d7c2aeb806cefe014236eb1c331d12032.
Audience
Section titled “Audience”- Developers integrating with control-plane workflows.
- Operators checking endpoint shape before using automation.
- Security reviewers checking that public docs do not invent routes.
What is this?
Section titled “What is this?”This page is generated from contracts/openapi/admin-api.yaml. It lists Admin API operations, grouped by product domain. It is a contract map, not a live API console.
When do I use it?
Section titled “When do I use it?”Use it when you need route, method, operation ID, response-code, or schema-reference names for control-plane workflows. Do not use this page as proof of authorization behavior; use the product page and runbook for that workflow.
What happens?
Section titled “What happens?”271operations are read from the OpenAPIpathsobject.- Operation IDs and summaries are copied from the spec.
- Schema references point back to OpenAPI components; JSON Schema references are listed on Schemas.
- No live unauthenticated Try It widget is generated.
Access
Section titled “Access”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
GET | /v1/admin/role-bindings | listRoleBindings | List gateway role bindings for the active tenant. | 200 |
POST | /v1/admin/role-bindings | createRoleBinding | Create a gateway role binding. | 201 |
POST | /v1/admin/role-bindings/preview | previewRoleBindings | Preview effective roles and collection permissions for a normalized actor context. | 200 |
PATCH | /v1/admin/role-bindings/{binding_id} | patchRoleBinding | Update a gateway role binding. | 200 |
POST | /v1/admin/role-bindings/{binding_id}/disable | disableRoleBinding | Disable a gateway role binding immediately. | 200 |
Admin Activity
Section titled “Admin Activity”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
GET | /v1/admin-activity | listAdminActivity | List curated admin activity rows backed by sanitized durable audit events. | 200, 400, 403 |
GET | /v1/admin-activity/{audit_event_id} | getAdminActivity | Read one curated admin activity detail by audit event ID. | 200, 400, 403, 404 |
Agents
Section titled “Agents”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
GET | /v1/agents | listAgents | List governed agent registry records with pagination, facets, search, and per-row permissions. | 200 |
POST | /v1/agents | createAgent | Submit an agent registry record for security approval. Created records are non-callable until approved. | 202, 409 |
GET | /v1/agents/{agent_id} | getAgentRegistryRecord | Read agent registry metadata, lifecycle state, allowed surfaces, environments, and instance identity. | 200 |
PATCH | /v1/agents/{agent_id} | patchAgentRegistryRecord | Edit agent governance metadata without making the agent callable unless it remains approved. | 202 |
POST | /v1/agents/{agent_id}/approval | transitionAgentApproval | Move an agent through approval, disabled, deprecated, or archived states. | 202 |
POST | /v1/agents/{agent_id}/revoke | revokeAgent | Disable an agent, append agent revocation outbox metadata, revoke affected active sessions, and audit the admin action. | 202 |
Approvals
Section titled “Approvals”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
GET | /v1/approvals | listApprovalsQueue | List reviewable submissions (decision workbench) across the tenant, all environments. | 200 |
POST | /v1/approvals/batch | batchApproveRegistrySubmissions | Batch approve eligible MCP server submissions using submission_id and manifest_hash pins. | 202 |
| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
POST | /v1/audit/search | searchAudit | Search tool, policy, session, credential, API adapter, and admin audit events. | 200, 403 |
POST | /v1/audit/exports | createAuditExport | Create an async metadata-only audit evidence export job. | 202, 400, 403, 422, 429 |
GET | /v1/audit/exports/{export_id} | getAuditExport | Read audit export job status and evidence metadata. | 200, 403, 404 |
GET | /v1/audit/exports/{export_id}/download | downloadAuditExport | Download a completed audit export artifact. | 200, 403, 404, 409, 410 |
GET | /v1/audit/requests/{request_id} | getAuditRequestBundle | Read the ordered audit event chain for one runtime request. | 200, 403 |
Client Surfaces
Section titled “Client Surfaces”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
GET | /v1/client-surfaces | listClientSurfaces | List canonical client surfaces visible in the requesting tenant and environment. | 200, 400, 403 |
GET | /v1/client-surfaces/{client_surface_id} | getClientSurface | Read canonical client-surface metadata for simulator, agent, audit, and emergency workflows. | 200, 403, 404 |
POST | /v1/client-surfaces/{client_surface_id}/lifecycle | transitionClientSurfaceLifecycle | Safely disable or revoke a client surface, audit the reason, and publish revocation impact. | 202, 400, 403, 404 |
Consumer Oauth
Section titled “Consumer Oauth”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
GET | /v1/consumer-oauth/authorization-server-profiles | listConsumerAuthorizationServerProfiles | List tenant-scoped OAuth authorization-server profiles. | 200, 403 |
POST | /v1/consumer-oauth/authorization-server-profiles | createConsumerAuthorizationServerProfile | Create a draft OAuth authorization-server profile. | 201, 403, 422 |
GET | /v1/consumer-oauth/authorization-server-profiles/{profile_id} | getConsumerAuthorizationServerProfile | Read one OAuth authorization-server profile. | 200, 403, 404 |
PATCH | /v1/consumer-oauth/authorization-server-profiles/{profile_id} | updateConsumerAuthorizationServerProfile | Update a draft, disabled, or version-compatible OAuth authorization-server profile. | 200, 403, 404, 409, 422 |
POST | /v1/consumer-oauth/authorization-server-profiles/{profile_id}/lifecycle | transitionConsumerAuthorizationServerProfile | Validate, activate, disable, re-enable, roll back, or retire an OAuth authorization-server profile. | 202, 403, 404, 409, 422 |
POST | /v1/consumer-oauth/authorization-server-profiles/{profile_id}/diagnostics | diagnoseConsumerAuthorizationServerProfile | Refresh and report safe OAuth metadata, JWKS, claim-mapping, and interoperability diagnostics. | 200, 403, 404 |
POST | /v1/consumer-oauth/authorization-server-profiles/{profile_id}/diagnostics/token | testConsumerOAuthAccessToken | Test a sample OAuth access token against a profile and endpoint binding. | 200, 403, 404, 422 |
GET | /v1/consumer-oauth/resource-auth-bindings | listMcpResourceAuthBindings | List endpoint-scoped consumer-auth bindings. | 200, 403 |
POST | /v1/consumer-oauth/resource-auth-bindings | createMcpResourceAuthBinding | Create a draft endpoint consumer-auth binding. | 201, 403, 409, 422 |
GET | /v1/consumer-oauth/resource-auth-bindings/{binding_id} | getMcpResourceAuthBinding | Read one endpoint consumer-auth binding. | 200, 403, 404 |
PATCH | /v1/consumer-oauth/resource-auth-bindings/{binding_id} | updateMcpResourceAuthBinding | Update a version-compatible endpoint consumer-auth binding. | 200, 403, 404, 409, 422 |
POST | /v1/consumer-oauth/resource-auth-bindings/{binding_id}/lifecycle | transitionMcpResourceAuthBinding | Activate, disable, roll back, or retire an endpoint consumer-auth binding. | 202, 403, 404, 409, 422 |
GET | /v1/consumer-oauth/resource-auth-bindings/{binding_id}/protected-resource-metadata | previewMcpProtectedResourceMetadata | Preview the RFC 9728 metadata and path-specific metadata URL for an endpoint binding. | 200, 403, 404 |
GET | /v1/consumer-oauth/resource-auth-bindings/{binding_id}/migration-status | getConsumerOAuthMigrationStatus | Read persisted migration evidence for one endpoint auth binding. | 200, 403, 404, 409 |
POST | /v1/consumer-oauth/revocations/preview | previewConsumerOAuthRevocation | Preview sessions, cached credentials, and data-plane instances affected by an OAuth revocation. | 200, 403, 422 |
GET | /v1/consumer-oauth/revocations | listConsumerOAuthRevocations | Search OAuth revocations and propagation status by governed identity or endpoint dimensions. | 200, 403 |
POST | /v1/consumer-oauth/revocations | createConsumerOAuthRevocation | Revoke a principal, OAuth client, auth profile, agent, workload, endpoint, or session. | 202, 403, 422 |
GET | /v1/consumer-oauth/revocations/{revocation_id} | getConsumerOAuthRevocation | Read OAuth revocation propagation status. | 200, 403, 404 |
GET | /v1/consumer-oauth/upstream-providers | listUpstreamOAuthProviders | List tenant-scoped upstream OAuth provider metadata. | 200, 403 |
POST | /v1/consumer-oauth/upstream-providers | createUpstreamOAuthProvider | Create a draft upstream OAuth provider. | 201, 403, 409, 422 |
GET | /v1/consumer-oauth/upstream-providers/{provider_id} | getUpstreamOAuthProvider | Read one upstream OAuth provider. | 200, 403, 404 |
PATCH | /v1/consumer-oauth/upstream-providers/{provider_id} | updateUpstreamOAuthProvider | Update a version-compatible upstream OAuth provider. | 200, 403, 404, 409, 422 |
POST | /v1/consumer-oauth/upstream-providers/{provider_id}/lifecycle | transitionUpstreamOAuthProvider | Validate, activate, disable, re-enable, or retire an upstream OAuth provider. | 202, 403, 404, 409, 422 |
POST | /v1/consumer-oauth/upstream-providers/{provider_id}/diagnostics | diagnoseUpstreamOAuthProvider | Test target-bound upstream token acquisition without calling a production tool. | 200, 403, 404, 422 |
GET | /v1/consumer-oauth/upstream-grants | listUpstreamOAuthGrants | List metadata-only user upstream OAuth grant and refresh health. | 200, 403 |
POST | /v1/consumer-oauth/upstream-grants/authorizations | initiateUpstreamOAuthGrantAuthorization | Create a short-lived user-bound upstream OAuth authorization. | 201, 401, 403, 409, 422 |
GET | /v1/consumer-oauth/upstream-grants/authorizations/connect | connectUpstreamOAuthGrantFromRuntimeTicket | Start upstream authorization from a short-lived runtime ticket. | 303, 401, 404, 409, 422 |
GET | /v1/consumer-oauth/upstream-grants/authorizations/{authorization_id}/connect | connectUpstreamOAuthGrantAuthorization | Verify the initiating user before redirecting to the upstream authorization server. | 303, 401, 404, 409 |
GET | /v1/consumer-oauth/upstream-grants/authorizations/callback | completeUpstreamOAuthGrantAuthorization | Complete a PKCE-bound upstream OAuth authorization callback. | 200, 401, 404, 409, 422 |
GET | /v1/consumer-oauth/upstream-grants/{grant_id} | getUpstreamOAuthGrant | Read one metadata-only upstream OAuth grant. | 200, 403, 404 |
POST | /v1/consumer-oauth/upstream-grants/{grant_id}/disconnect | disconnectUpstreamOAuthGrant | Disconnect and revoke an upstream OAuth grant. | 202, 403, 404, 409 |
Credential Bindings
Section titled “Credential Bindings”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
GET | /v1/credential-bindings | listCredentialBindings | List credential binding metadata with server-side search, filters, KPIs, facets, and permissions. | 200 |
POST | /v1/credential-bindings | createCredentialBinding | Submit a credential binding record for security approval without exposing credential material. | 202 |
GET | /v1/credential-bindings/{credential_binding_id} | getCredentialBinding | Read credential binding detail, approved projection, broker check, activity, and permissions. | 200, 403 |
PATCH | /v1/credential-bindings/{credential_binding_id} | updateCredentialBinding | Update credential binding metadata or submit approval-impacting changes for re-review. | 202, 403 |
POST | /v1/credential-bindings/{credential_binding_id}/approval | transitionCredentialBindingApproval | Move a credential binding through approval states. Disable/revoke use dedicated endpoints. | 202, 403 |
POST | /v1/credential-bindings/{credential_binding_id}/rotate | rotateCredentialBinding | Rotate credential binding reference metadata without accepting credential material. | 202, 403 |
POST | /v1/credential-bindings/{credential_binding_id}/disable | disableCredentialBinding | Disable a credential binding so new broker resolutions and upstream calls fail closed. | 202, 403 |
POST | /v1/credential-bindings/{credential_binding_id}/revoke | revokeCredentialBinding | Revoke a credential binding, emit revocation fanout, and terminate affected sessions. | 202, 403 |
POST | /v1/credential-bindings/{credential_binding_id}/rollback | rollbackCredentialBinding | Activate a prior immutable approved credential-binding version. | 202, 403, 404, 409 |
Data Planes
Section titled “Data Planes”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
GET | /v1/data-planes | getDataPlanes | List data-plane topology and health metadata for a tenant/environment scope. | 200, 403 |
GET | /v1/data-planes/{data_plane_id} | getDataPlane | Inspect one data plane with topology, health, sync, sessions, drain, upgrade, backup, and trust-boundary metadata. | 200, 403, 404 |
Deny Diagnostics
Section titled “Deny Diagnostics”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
POST | /v1/deny-diagnostics | createDenyDiagnosticsBundle | Build a metadata-only deny diagnostics bundle from a denied request, audit event, or explicit actor/tool context. | 200, 400, 403, 404 |
POST | /v1/deny-diagnostics/remediations | listDenyDiagnosticsRemediations | List the bounded set of mechanical remediation options for one denial. | 200, 400, 403, 404 |
POST | /v1/deny-diagnostics/remediation-impact | evaluateDenyDiagnosticsRemediationImpact | Evaluate a candidate policy manifest against the denial, comparable stored denials, and other subjects. | 200, 400, 403, 404 |
Deployment
Section titled “Deployment”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
GET | /v1/deployment/status | getDeploymentStatus | Inspect data plane, database, cache, connector, topology, telemetry, and version status. | 200 |
GET | /v1/control-plane/scope | getControlPlaneScope | Read the backend-resolved tenant and environment scope for UI registration workflows. | 200 |
Emergency Disable
Section titled “Emergency Disable”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
POST | /v1/emergency-disable | emergencyDisable | Disable a server, tool, API source, agent, credential, connector, or client surface. | 202 |
Environments
Section titled “Environments”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
GET | /v1/environments | listEnvironments | List tenant environments for settings/topology awareness without changing current scope. | 200, 403 |
GET | /v1/environments/{environment_id} | getEnvironment | Read one tenant-scoped environment settings record without switching UI scope. | 200, 403, 404 |
Gateway Managed Secrets
Section titled “Gateway Managed Secrets”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
GET | /v1/gateway-managed-secrets | listManagedSecrets | List gateway-managed secret metadata for the scope. | 200, 403 |
POST | /v1/gateway-managed-secrets | createManagedSecret | Vault a secret value with the gateway. | 201, 400, 403, 503 |
Governance
Section titled “Governance”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
GET | /v1/mcp-servers | listMcpServerRegistryRecords | List MCP server registry records with UI-ready envelope metadata. | 200 |
POST | /v1/mcp-servers | registerMcpServer | Register or submit an MCP server manifest for approval. | 202 |
GET | /v1/mcp-servers/{server_id} | getMcpServerRegistryRecord | Read an MCP server registry record with owner, health, approval, and history. | 200 |
PATCH | /v1/mcp-servers/{server_id}/catalog-visibility | patchMcpServerCatalogVisibility | Change owner-curated catalog visibility for an MCP server and append durable admin audit. | 200, 403 |
GET | /v1/mcp-servers/{server_id}/activity | listMcpServerActivity | Read typed MCP server activity from submission, snapshot, and change metadata. | 200 |
GET | /v1/mcp-servers/{server_id}/policy-credentials | getMcpServerPolicyCredentials | Read backend-owned policy, credential, connector, and access posture for one MCP server. | 200, 403, 404 |
GET | /v1/mcp-servers/{server_id}/usage | getMcpServerUsage | Read backend-owned usage rollups for one MCP server. | 200, 400, 403, 404 |
POST | /v1/mcp-servers/{server_id}/validate | validateMcpServerManifest | Validate a proposed manifest for a specific MCP server. | 200 |
PATCH | /v1/mcp-servers/{server_id}/owner | editMcpServerOwner | Submit an immutable owner metadata edit for an MCP server. | 202, 403 |
POST | /v1/mcp-servers/{server_id}/registration-status/deprecate | deprecateMcpServerRegistrationStatus | Submit an immutable registration_status=deprecated edit for an MCP server. | 202 |
GET | /v1/mcp-servers/{server_id}/pending-submission/compare-live | compareMcpServerPendingSubmissionToLive | Compare the pending MCP server submission against the live snapshot. | 200 |
POST | /v1/mcp-servers/{server_id}/approval | transitionMcpServerApproval | Compatibility shim for non-terminal review and live-resource lifecycle transitions; approval/rejection require submission_id and manifest_hash. | 202 |
POST | /v1/mcp-servers/{server_id}/submissions | submitMcpServerManifestRevision | Submit a new immutable manifest for an existing MCP server without changing the live snapshot. | 202 |
GET | /v1/mcp-servers/{server_id}/submissions | listMcpServerSubmissions | List immutable MCP server submissions for audit and review context. | 200 |
GET | /v1/mcp-servers/{server_id}/submissions/{submission_id} | getMcpServerSubmission | Read one immutable MCP server submission and its safe manifest snapshot. | 200 |
POST | /v1/mcp-servers/{server_id}/submissions/{submission_id}/review | reviewMcpServerSubmission | Review a specific submission by submission_id and manifest_hash; approval creates an immutable live snapshot. | 202, 409 |
POST | /v1/mcp-servers/{server_id}/lifecycle | transitionMcpServerLifecycle | Disable or archive the live MCP server resource without changing submission history. | 202 |
GET | /v1/mcp-servers/{server_id}/versions | listMcpServerVersions | List approved immutable snapshots only, newest first. | 200 |
GET | /v1/mcp-servers/{server_id}/versions/compare | compareMcpServerVersions | Compare two approved backend snapshot IDs. | 200 |
GET | /v1/mcp-servers/{server_id}/versions/{snapshot_id} | getMcpServerVersion | Read one approved immutable snapshot by snapshot_id. | 200 |
GET | /v1/mcp-servers/{server_id}/health | getMcpServerHealth | Query backend health and route availability for a registered MCP server. | 200 |
POST | /v1/mcp-servers/{server_id}/reprobe | reprobeMcpServer | Re-probe an approved registered MCP server from its immutable live snapshot. | 200, 403, 404, 409, 500, 503 |
POST | /v1/mcp-servers/{server_id}/tools/{tool_name}/try | tryMcpServerTool | Run one governed test call against a live MCP server tool. | 200, 403, 404, 409 |
GET | /v1/api-sources | listApiSources | List API sources for one tenant/environment with filters, facets, and safe summary metadata. | 200, 403 |
POST | /v1/api-sources/preview | previewApiSourceImport | Preview an API contract import without persisting a registry record. | 200, 400, 403 |
POST | /v1/api-sources/import | importOpenApiSource | Import an API contract and create gateway-hosted MCP tool candidates. | 202 |
GET | /v1/api-sources/{api_source_id} | getApiSourceRegistryRecord | Read an API source registry record with approved operations, health, and history. | 200 |
PATCH | /v1/api-sources/{api_source_id}/catalog-visibility | patchApiSourceCatalogVisibility | Change owner-curated catalog visibility for an API source and append durable admin audit. | 200, 403 |
POST | /v1/api-sources/{api_source_id}/approval | transitionApiSourceApproval | Move an API source or selected operation through the approval lifecycle. | 202 |
GET | /v1/api-sources/{api_source_id}/mappings | listApiSourceMappings | Read backend-generated API-to-MCP mappings for an API source. | 200, 403, 404 |
POST | /v1/api-sources/{api_source_id}/tools/try | tryApiSourceTool | Run one approved API-backed tool from the authenticated console. | 200, 400, 403, 404 |
GET | /v1/catalog/capabilities | listCatalogCapabilities | List policy-visible and owner-tier-visible capabilities for the authenticated actor. | 200, 401 |
GET | /v1/catalog/capabilities/{capability_id} | getCatalogCapability | Read one visible catalog capability without revealing hidden or out-of-scope existence. | 200, 404 |
POST | /v1/catalog/access-requests | createCatalogAccessRequest | Request access to one visible catalog source or a visible tool subset. | 201, 404, 409 |
GET | /v1/catalog/access-requests | listCatalogAccessRequests | List the caller’s requests or the permission-gated review queue. | 200, 403 |
POST | /v1/catalog/access-requests/{request_id}/approve | approveCatalogAccessRequest | Approve a pending request and publish its scoped policy grant. | 200, 403, 409 |
POST | /v1/catalog/access-requests/{request_id}/deny | denyCatalogAccessRequest | Deny a pending request with a machine-readable reason. | 200, 400, 403, 409 |
POST | /v1/catalog/access-requests/{request_id}/cancel | cancelCatalogAccessRequest | Cancel the caller’s own pending request. | 200, 403, 409 |
GET | /v1/mcp-servers/{server_id}/traffic-limits | getMcpServerTrafficLimit | Read the traffic limit profile for an MCP server. | 200, 403, 404 |
PUT | /v1/mcp-servers/{server_id}/traffic-limits | upsertMcpServerTrafficLimit | Publish or revise the traffic limit profile for an MCP server. | 200, 400, 403, 503 |
GET | /v1/mcp-servers/{server_id}/audit | getMcpServerAudit | Search audit events for one MCP server. | 200, 403 |
GET | /v1/mcp-servers/{server_id}/denied-attempts | getMcpServerDeniedAttempts | Recent denied tool-call attempts for one MCP server, backed by audit search. | 200, 403 |
Hosted
Section titled “Hosted”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
GET | /v1/hosted/auth/csrf | getHostedAuthCsrf | Issue a hosted auth CSRF token and HttpOnly Secure SameSite CSRF cookie. | 200, 403 |
POST | /v1/hosted/auth/signup | signupHostedAuth | Create a work-domain hosted email-password account and restricted pre-activation session. | 201, 400, 429 |
POST | /v1/hosted/auth/signup/resend-confirmation | resendHostedSignupConfirmation | Neutrally accept a hosted email confirmation resend request. | 200, 429 |
POST | /v1/hosted/auth/signup/confirm | confirmHostedSignup | Consume a hosted email confirmation challenge and activate membership when eligible. | 200 |
POST | /v1/hosted/auth/login | loginHostedAuth | Create a hosted browser session for an email-password account. | 200, 429 |
GET | /v1/hosted/auth/entry-status | getHostedAuthEntryStatus | Resume the restricted hosted account-entry journey. | 200, 401, 403 |
POST | /v1/hosted/auth/logout | logoutHostedAuth | Revoke the hosted browser session and clear hosted cookies. | 200 |
GET | /v1/hosted/social-auth/providers | listHostedSocialAuthProviders | List hosted Google, Microsoft, and GitHub signup/login providers. | 200, 403 |
POST | /v1/hosted/social-auth/begin | beginHostedSocialAuth | Begin hosted Google, Microsoft, or GitHub signup/login. | 200, 400, 403, 429 |
POST | /v1/hosted/social-auth/callback | completeHostedSocialAuthCallback | Complete a normalized hosted social auth callback in test environments. | 200, 400, 403 |
GET | /v1/hosted/social-auth/google/callback | completeHostedGoogleSocialAuthCallback | Complete hosted Google signup/login from the provider redirect. | 303 |
GET | /v1/hosted/social-auth/github/callback | completeHostedGithubSocialAuthCallback | Complete hosted GitHub signup/login from the provider redirect. | 303 |
POST | /v1/hosted/auth/password-reset | requestHostedPasswordReset | Request a hosted password reset challenge without disclosing account existence. | 200, 429 |
POST | /v1/hosted/auth/password-reset/complete | completeHostedPasswordReset | Consume a single-use hosted reset challenge and set a new password. | 200 |
POST | /v1/hosted/auth/password/change | changeHostedPassword | Add or change the password for an active hosted browser session. | 200 |
GET | /v1/hosted/current-user | getHostedCurrentUser | Read the managed current-user identity and stable capability set. | 200, 401, 403 |
POST | /v1/hosted/voice/session | createHostedVoiceSession | Mint a short-lived voice provider session for the active managed user. | 200, 401, 404 |
GET | /v1/hosted/current-user/browser-sessions | listHostedBrowserSessions | List active browser sessions for the managed current user. | 200, 401 |
POST | /v1/hosted/current-user/browser-sessions/revoke-others | revokeOtherHostedBrowserSessions | Revoke every browser session except the current managed session. | 200, 403 |
POST | /v1/hosted/current-user/membership/leave | leaveHostedOrganization | Leave the current managed organization. | 200, 400, 401, 403, 409 |
GET | /v1/hosted/organization/upgrade-request | getHostedOrganizationUpgradeRequest | Read the session-derived organization upgrade-request status. | 200, 403 |
POST | /v1/hosted/organization/upgrade-request | submitHostedOrganizationUpgradeRequest | Submit the current managed organization for manual upgrade review. | 200, 403 |
GET | /v1/hosted/organization/members | listHostedOrganizationMembers | List members in the session-derived managed organization. | 200, 403 |
GET | /v1/hosted/organization/members/{member_ref} | getHostedOrganizationMember | Read one member in the session-derived managed organization. | 200, 404 |
DELETE | /v1/hosted/organization/members/{member_ref} | removeHostedOrganizationMember | Remove a member from the session-derived managed organization. | 200, 403, 409 |
PATCH | /v1/hosted/organization/members/{member_ref}/role | changeHostedOrganizationMemberRole | Change a managed organization member role. | 200, 403, 409 |
POST | /v1/hosted/organization/members/{member_ref}/suspend | suspendHostedOrganizationMember | Suspend a managed organization member and revoke browser sessions. | 200, 403, 409 |
POST | /v1/hosted/organization/members/{member_ref}/reactivate | reactivateHostedOrganizationMember | Reactivate a suspended managed organization member. | 200, 403, 409 |
POST | /v1/hosted/organization/members/{member_ref}/revoke-browser-sessions | revokeHostedOrganizationMemberBrowserSessions | Revoke all browser sessions for a managed organization member. | 200, 403, 409 |
GET | /v1/hosted/account-settings | getHostedAccountSettings | Read hosted workspace settings and account security state. | 200, 403 |
PATCH | /v1/hosted/workspace-profile | updateHostedWorkspaceProfile | Update the hosted workspace display name. | 200, 403 |
PATCH | /v1/hosted/activation-policy | updateHostedActivationPolicy | Update hosted activation policy defaults for future resource activation. | 200, 400, 403 |
POST | /v1/hosted/orgs/trials | createHostedTrialOrg | Create a hosted trial org after verified work-domain signup. | 201, 400, 403 |
GET | /v1/hosted/orgs/{org_ref} | getHostedOrg | Read hosted org lifecycle, trial, plan, and entitlement state. | 200, 404 |
POST | /v1/hosted/orgs/{org_ref}/upgrade-request | requestHostedOrgUpgrade | Mark that a locked or trial org requested upgrade. | 202 |
POST | /v1/hosted/orgs/{org_ref}/trial/expire | expireHostedOrgTrialForSmoke | Prove hosted trial expiry hard-lock for public smoke. | 200 |
POST | /v1/hosted/orgs/{org_id}/trial/extend | extendHostedOrgTrial | DAC operator extends a hosted trial and unlocks trial entitlements. | 202 |
PUT | /v1/hosted/orgs/{org_id}/plan | setHostedOrgPlan | DAC operator manually sets hosted plan state. | 202 |
POST | /v1/hosted/orgs/{org_id}/lock | lockHostedOrg | DAC operator locks a hosted org and disables runtime/configuration entitlements. | 202 |
POST | /v1/hosted/orgs/{org_id}/restore-access | restoreHostedOrgAccess | DAC operator restores hosted org access according to current trial and plan state. | 202 |
POST | /v1/hosted/email/challenges | createHostedEmailChallenge | Issue a hosted-only email verification challenge. | 202, 503 |
POST | /v1/hosted/email/challenges/verify-code | verifyHostedEmailCode | Verify a hosted email challenge with a short code. | 200 |
POST | /v1/hosted/email/challenges/verify-link | verifyHostedEmailLink | Verify a hosted email challenge with a magic-link token. | 200 |
GET | /v1/hosted/invites | listHostedInvites | List hosted invites for admin management. | 200 |
POST | /v1/hosted/invites | createHostedInvite | Invite a security/admin, developer, or viewer user to a hosted org. | 201 |
POST | /v1/hosted/invites/{invite_id}/resend | resendHostedInvite | Resend a pending hosted invite with a rotated action ref. | 200 |
POST | /v1/hosted/invites/{invite_id}/cancel | cancelHostedInvite | Cancel a pending hosted invite. | 200 |
POST | /v1/hosted/auth/invite-binding | bindHostedInviteContinuation | Bind an invite email continuation to this browser. | 200 |
POST | /v1/hosted/invites/accept | acceptHostedInvite | Accept a hosted invite after email verification. | 200 |
POST | /v1/hosted/domain-signups/resolve | resolveHostedDomainSignup | Resolve hosted signup route for a verified domain. | 200, 400, 403 |
GET | /v1/hosted/join-requests | listHostedJoinRequests | List hosted same-domain access requests for admin review. | 200 |
POST | /v1/hosted/join-requests | createHostedJoinRequest | Create a same-domain hosted access request. | 201, 409 |
POST | /v1/hosted/join-requests/{join_request_ref}/approve | approveHostedJoinRequest | Approve a same-domain hosted access request. | 200, 403 |
POST | /v1/hosted/join-requests/{join_request_ref}/reject | rejectHostedJoinRequest | Reject a same-domain hosted access request. | 200, 403 |
GET | /v1/hosted/join-requests/{join_request_ref}/public-status | getHostedJoinRequestPublicStatus | Read neutral public status for a hosted access request. | 200, 404 |
POST | /v1/hosted/separate-workspace-requests | createHostedSeparateWorkspaceRequest | Request a separate hosted workspace for an existing domain. | 201, 409 |
POST | /v1/hosted/separate-workspace-requests/{request_id}/review | reviewHostedSeparateWorkspaceRequest | DAC operator reviews a separate hosted workspace request. | 202, 403 |
POST | /v1/hosted/runtime/endpoints | registerHostedRuntimeEndpoint | Register a customer-owned HTTPS API or HTTPS MCP endpoint for hosted runtime. | 201, 400 |
POST | /v1/hosted/runtime/endpoints/{endpoint_ref}/reachability | validateHostedRuntimeEndpointReachability | Run hosted runtime reachability validation from DAC egress. | 202, 409 |
POST | /v1/hosted/runtime/endpoints/{endpoint_ref}/readiness | evaluateHostedRuntimeEndpointReadiness | Evaluate hosted runtime route readiness for a governed call. | 200 |
GET | /v1/hosted/audit/posture | getHostedAuditPosture | Read hosted audit posture with metadata-only defaults. | 200, 403 |
POST | /v1/hosted/payload-capture/windows | createHostedPayloadCaptureWindow | Create a short-lived hosted payload-capture window. | 201, 400, 403 |
POST | /v1/hosted/payload-capture/windows/{window_id}/evaluate | evaluateHostedPayloadCaptureWindow | Evaluate whether a runtime request falls inside a capture window. | 200, 403 |
POST | /v1/hosted/payload-capture/windows/{window_id}/ttl-purge | evaluateHostedPayloadCaptureTtlPurge | Evaluate TTL purge for an expired or suspended hosted capture window. | 200 |
POST | /v1/hosted/payload-capture/windows/{window_id}/incident-action | applyHostedPayloadCaptureIncidentAction | Apply a DAC operator incident action to a hosted capture window. | 200, 403 |
POST | /v1/hosted/audit/runtime-events | appendHostedRuntimeMetadataAuditEvent | Append hosted runtime metadata audit evidence. | 202, 400 |
Identity
Section titled “Identity”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
GET | /v1/identity/me | getIdentityMe | Read the normalized authenticated admin actor and backend-computed collection permissions. | 200 |
GET | /v1/identity-provider | getIdentityProvider | Read metadata-only active auth mode and provider configuration state. | 200 |
POST | /v1/identity-provider/diagnostics | diagnoseIdentityProvider | Run metadata-only auth provider readiness checks. | 200 |
POST | /v1/local-identity/bootstrap-admin | bootstrapLocalIdentityAdmin | Bootstrap the first local platform admin before any local user exists. | 201 |
POST | /v1/local-identity/login | loginLocalIdentity | Create a backend-owned local browser session. | 200 |
POST | /v1/local-identity/logout | logoutLocalIdentity | Revoke the active local browser session. | 200 |
GET | /v1/local-identity/session | getLocalIdentitySession | Read the current local browser session and normalized actor. | 200 |
GET | /v1/local-identity/users | listLocalIdentityUsers | List local users without password hashes. | 200 |
POST | /v1/local-identity/users | createLocalIdentityUser | Create a local user and return a generated temporary password once when omitted. | 201 |
PATCH | /v1/local-identity/users/{user_id} | patchLocalIdentityUser | Update local user profile metadata. | 200 |
POST | /v1/local-identity/users/{user_id}/disable | disableLocalIdentityUser | Disable a local user and revoke active local sessions. | 200 |
POST | /v1/local-identity/users/{user_id}/reset-password | resetLocalIdentityUserPassword | Reset a local user’s password and return the temporary password once. | 200 |
POST | /v1/local-identity/users/{user_id}/change-password | changeLocalIdentityUserPassword | Change the authenticated local user’s password and clear reset-required state. | 200 |
GET | /v1/local-identity/groups | listLocalIdentityGroups | List local groups and member IDs. | 200 |
POST | /v1/local-identity/groups | createLocalIdentityGroup | Create a local group principal. | 201 |
PATCH | /v1/local-identity/groups/{group_id} | patchLocalIdentityGroup | Update local group metadata. | 200 |
POST | /v1/local-identity/groups/{group_id}/members | addLocalIdentityGroupMember | Add a local user to a local group. | 200 |
DELETE | /v1/local-identity/groups/{group_id}/members/{user_id} | removeLocalIdentityGroupMember | Remove a local user from a local group. | 200 |
GET | /v1/local-identity/service-accounts | listLocalIdentityServiceAccounts | List local service accounts without token hashes. | 200 |
POST | /v1/local-identity/service-accounts | createLocalIdentityServiceAccount | Create a local service principal. | 201 |
GET | /v1/local-identity/service-accounts/{service_id}/tokens | listLocalIdentityServiceAccountTokens | List service-account token metadata without token hashes or plaintext tokens. | 200 |
POST | /v1/local-identity/service-accounts/{service_id}/tokens | createLocalIdentityServiceAccountToken | Create a service-account token and return plaintext once. | 200 |
POST | /v1/local-identity/service-accounts/{service_id}/tokens/{token_id}/revoke | revokeLocalIdentityServiceAccountToken | Revoke one service-account token by metadata ID. | 200 |
POST | /v1/local-identity/service-accounts/{service_id}/disable | disableLocalIdentityServiceAccount | Disable a local service account and revoke active tokens. | 200 |
License
Section titled “License”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
GET | /v1/license | getLicenseStatus | Read safe license and entitlement status for one environment. | 200, 403 |
Managed
Section titled “Managed”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
GET | /v1/managed/plans | listManagedPlans | List the offers in the current approved managed catalog release. | 200, 401, 403, 503 |
GET | /v1/managed/plan | getManagedPlan | Read the current member’s managed plan and usage. | 200, 401, 403, 503 |
POST | /v1/managed/plan-change-requests | createManagedPlanChangeRequest | Request a change to another managed plan. | 202, 400, 401, 403, 409, 503 |
GET | /v1/managed/invocations/{receipt} | getManagedInvocationStatus | Read pending or terminal managed invocation metadata. | 200, 401, 404, 503 |
| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
POST | /v1/mcp/api-sources/{api_source_id} | apiSourceMcpJsonRpc | Legacy Streamable HTTP MCP JSON-RPC endpoint for one approved API-source import. | 200, 202, 400, 401, 404, 415 |
POST | /v1/mcp/api-sources/{api_source_id}/mcp | apiSourceMcpJsonRpcAlias | Preferred Streamable HTTP MCP JSON-RPC endpoint for one approved API-source import. | 200, 202, 400, 401, 404, 415 |
Oauth Protected Resource
Section titled “Oauth Protected Resource”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
GET | /.well-known/oauth-protected-resource/tenants/{tenant_id}/environments/{environment_id}/servers/{server_id}/mcp | getMcpServerProtectedResourceMetadata | Read path-specific RFC 9728 metadata for a registered MCP server resource. | 200, 404, 503 |
GET | /.well-known/oauth-protected-resource/tenants/{tenant_id}/environments/{environment_id}/api-sources/{api_source_id}/mcp | getApiSourceProtectedResourceMetadata | Read path-specific RFC 9728 metadata for an API-source MCP resource. | 200, 404, 503 |
Operations
Section titled “Operations”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
GET | /v1/telemetry | getTelemetrySettings | Read metadata-only telemetry configuration and delivery health. | 200, 403 |
PUT | /v1/telemetry | updateTelemetrySettings | Update telemetry mode and destination references with write-only secret refs. | 200, 403 |
POST | /v1/telemetry/test | testTelemetrySettings | Run a metadata-only telemetry destination check. | 202, 403 |
POST | /v1/telemetry/disable | disableTelemetrySettings | Disable telemetry export for an environment. | 202, 403 |
GET | /v1/siem-webhooks | listSiemWebhooks | List metadata-only SIEM and webhook destination configuration. | 200, 403 |
POST | /v1/siem-webhooks | createSiemWebhook | Create a SIEM/webhook destination using reference-only or write-only secret inputs. | 201, 403 |
PUT | /v1/siem-webhooks/{destination_id} | updateSiemWebhook | Update SIEM/webhook destination metadata and write-only delivery refs. | 200, 403, 404 |
POST | /v1/siem-webhooks/{destination_id}/test | testSiemWebhook | Run a metadata-only SIEM/webhook delivery check. | 202, 403, 404 |
POST | /v1/siem-webhooks/{destination_id}/disable | disableSiemWebhook | Disable a SIEM/webhook destination without deleting audit-export history. | 202, 403, 404 |
GET | /v1/connectors | listConnectors | List connector registry read-model rows for the UI with safe health, route, lifecycle, KPI, and permission metadata. | 200, 422, 403 |
GET | /v1/connectors/{connector_id} | getConnector | Read connector registry detail metadata for UI rendering without client-side status, audit, route, or session joins. | 200, 403, 404 |
GET | /v1/connectors/{connector_id}/impact | getConnectorImpact | Read safe connector blast-radius metadata before a lifecycle action. | 200, 403, 404, 500 |
POST | /v1/connectors/{connector_id}/lifecycle | transitionConnectorLifecycle | Move a connector through explicit lifecycle transitions without patching raw fields. | 200, 403, 404, 409, 422, 500 |
Policy
Section titled “Policy”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
GET | /v1/reason-codes | listReasonCodes | List backend-owned governance reason codes. | 200 |
POST | /v1/reason-codes | createReasonCode | Create or replace a tenant governance reason code. | 202 |
GET | /v1/reason-codes/export | exportReasonCodes | Export tenant governance reason-code catalog. | 200 |
POST | /v1/reason-codes/import | importReasonCodes | Import tenant governance reason-code catalog entries. | 200 |
PATCH | /v1/reason-codes/{code} | patchReasonCode | Update a tenant governance reason code. | 200 |
POST | /v1/policies/simulate | simulatePolicy | Preview a V1 gateway policy decision without runtime mutation. | 200 |
GET | /v1/policies | listPolicies | List policy versions for the scoped tenant and environment. | 200, 403 |
POST | /v1/policies | createPolicy | Create a brand-new draft policy version with no parent. | 201, 400, 403, 409 |
POST | /v1/policies/resolve-refs | resolvePolicyRefs | Resolve policy refs for manifest validation and policy picker flows. | 200, 400 |
GET | /v1/policies/{policy_version} | readPolicy | Read a policy version including editable safe body, validation, usage, hash, and permissions. | 200, 403, 404 |
PUT | /v1/policies/{policy_version} | updatePolicyDraft | Update a draft policy body with manifest_hash or etag concurrency pinning. | 202, 400, 403, 409 |
POST | /v1/policies/{policy_version}/validate | validatePolicyVersion | Validate a stored or supplied policy body and return structured errors. | 200, 403, 409 |
POST | /v1/policies/{policy_version}/publish | publishPolicyVersion | Publish a draft policy version and make it active for the environment. | 202, 403, 409, 422 |
POST | /v1/policies/{policy_version}/archive | archivePolicyVersion | Archive a draft, rejected, or safe old policy version. | 202, 403, 409 |
Registry
Section titled “Registry”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
POST | /v1/registry/validate-manifest | validateRegistryManifest | Validate MCP server or API source manifests without publishing them. | 200 |
GET | /v1/registry/mcp-compatibility/options | getMcpCompatibilityOptions | Read MCP compatibility choices and the effective configuration envelope. | 200, 403, 404 |
POST | /v1/registry/probe-mcp-server | probeMcpServer | Probe an MCP server from its configured runtime route and return compatibility evidence. | 200, 422 |
GET | /v1/registry/probes/{probe_id} | getMcpServerProbe | Read the most recent in-memory MCP server probe result. | 200, 404 |
Runtime
Section titled “Runtime”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
POST | /v1/runtime/audit-events | ingestRuntimeAuditEvents | Ingest metadata-only DP runtime audit events into CP audit storage. | 202, 400, 403 |
Sessions
Section titled “Sessions”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
POST | /v1/revocations | revokeAccess | Apply a target revocation and revoke affected active sessions. | 202, 403 |
POST | /v1/revocations/preview | previewRevocation | Preview active sessions and backend sessions affected by a target revocation. | 200, 403 |
GET | /v1/sessions | listActiveSessions | Query durable active session metadata. | 200, 403 |
POST | /v1/sessions/batch-revoke | batchRevokeSessions | Revoke selected sessions in one backend call. | 200, 403 |
GET | /v1/sessions/{client_session_id} | getSessionLifecycle | Read durable session metadata, backend sessions, transitions, and allowed actions. | 200, 403 |
POST | /v1/sessions/{client_session_id}/terminate | terminateSession | Explicitly terminate a client session and fail closed for future calls. | 202, 403 |
POST | /v1/sessions/{client_session_id}/revoke | revokeSession | Revoke an active client session and affected backend sessions through the internal outbox path. | 202, 403 |
Tenants
Section titled “Tenants”| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
POST | /tenants/{tenant_id}/environments/{environment_id}/servers/{server_id}/mcp | pathScopedMcpServerPost | Path-scoped MCP Streamable HTTP request for one registered server. | 200, 202, 400, 401, 403, 429, 503 |
GET | /tenants/{tenant_id}/environments/{environment_id}/servers/{server_id}/mcp | pathScopedMcpServerGet | Check path-scoped MCP Streamable HTTP GET support. | 405, 401, 403, 429, 503 |
DELETE | /tenants/{tenant_id}/environments/{environment_id}/servers/{server_id}/mcp | pathScopedMcpServerDelete | Delete a path-scoped MCP session after authenticating the request actor. | 202, 401, 403, 429, 503 |
POST | /tenants/{tenant_id}/environments/{environment_id}/api-sources/{api_source_id}/mcp | pathScopedApiSourceMcpPost | Path-scoped MCP Streamable HTTP request for one approved API source. | 200, 202, 400, 401, 403, 429, 503 |
| Method | Path | Operation | Summary | Responses |
|---|---|---|---|---|
GET | /api/v1/hosted/auth/social/google/callback | completeHostedGoogleSocialAuthApiCallback | Complete hosted Google signup/login through the public API prefix. | 303 |
GET | /api/v1/hosted/auth/social/github/callback | completeHostedGithubSocialAuthApiCallback | Complete hosted GitHub signup/login through the public API prefix. | 303 |
POST | /internal/v1/managed/assignments | assignManagedTenantFromRoster | Apply one approved commercial-roster assignment. | 200, 400, 401, 403, 404, 409, 503 |
POST | /internal/v1/managed/quota-periods/{quota_period_ref}/support-credit-requests | createManagedSupportCreditRequest | Request a managed quota support credit. | 200, 400, 401, 403, 404, 409, 503 |
POST | /internal/v1/managed/support-credit-requests/{request_ref}/approve | approveManagedSupportCreditRequest | Approve an above-threshold managed support credit. | 200, 400, 401, 403, 404, 409, 503 |
GET | /internal/v1/runtime/projection | getRuntimeProjection | Export one CP-published runtime projection to its scoped managed data plane. | 200, 403, 503 |
POST | /internal/v1/runtime/fleet/sessions | createManagedFleetHeartbeatSession | 201, 401, 409, 503 | |
GET | /internal/v1/runtime/fleet/projection | getManagedFleetProjection | 200, 401, 409, 503 | |
POST | /internal/v1/runtime/fleet/heartbeats | postManagedFleetHeartbeat | 200, 400, 401, 409, 503 | |
GET | /internal/v1/runtime/fleet/readiness | getManagedFleetReadiness | 200, 401, 409, 503 | |
POST | /internal/v1/runtime/consumer-oauth/jwks-refresh-signals | signalConsumerOAuthJwksRefresh | Submit bounded unknown-key refresh signals from a data plane. | 202, 400, 403 |
POST | /internal/v1/runtime/consumer-oauth/revocation-acknowledgements | acknowledgeConsumerOAuthRevocations | Acknowledge locally applied Consumer OAuth revocations. | 202, 400, 401, 403, 503 |
What can go wrong?
Section titled “What can go wrong?”- A route exists in implementation but not OpenAPI. Update the spec first.
- A public page hand-copies an endpoint and drifts from the spec.
- A docs console tries to send unauthenticated calls. That is out of scope until secured docs-console auth exists.
- A response example includes request bodies, response bodies, tokens, credentials, or customer data. Public reference output must stay metadata-only.
Source truth
Section titled “Source truth”- Read Schemas for JSON Schema contracts.
- Read gatewayctl for CLI parity surfaces.
- Read Audit Events for retained event fields.
Type set in Geist, Source Serif 4, and Departure Mono.