API documentation

Vertex AI authority surface

Use Decionis inside Vertex AI workflows without moving decision logic into the model layer. The adapter records observational evidence; consequential writes require canonical exact-action authority and a live pre-commit claim.

Overview

This page documents the shareable import path for Google Cloud and Vertex AI partners.

Decision boundary

Vertex AI is the distribution surface. Decionis Protocol remains the execution-time execution authority. The adapter route does request normalization and response shaping only.

Current auth posture

The adapter always uses a Decionis org API key. It can now also verify an optional or required Google identity token at the adapter edge, which is the bridge toward Workload Identity Federation without moving policy logic into Vertex.

Use the adapter, not raw policy logic in Vertex

The OpenAPI artifact is intentionally thin. It describes a governed verification tool, not a second policy runtime. Keep policy versions, approvals, dossiers, and verification evidence inside Decionis surfaces.

Spec URL

This is the immediate shareable path for partner engineering teams.

OpenAPI artifact

Download or mirror this spec into a Google Cloud-controlled location if your import process prefers GCS-hosted artifacts.

https://docs.decionis.com/openapi/decionis-vertex-extension-v1.yaml

Companion references

Use the API and Decision Dossier pages alongside the spec when a partner needs the adjacent contract details.

Need	Path
API overview	https://docs.decionis.com/api
Auth posture	https://docs.decionis.com/auth
Decision Dossier verification	https://docs.decionis.com/decision-dossier
Generic quickstart	https://docs.decionis.com/quickstart
Tool bundle	https://docs.decionis.com/google-cloud/vertex/decionis-vertex-authority-tool-bundle.json
Reference flow	https://docs.decionis.com/examples/decionis-vertex-reference-flow.json
Standalone Agent Card	https://docs.decionis.com/google-cloud/vertex/decionis-vertex-agent-card.json
A2A discovery profile	https://docs.decionis.com/google-cloud/vertex/decionis-vertex-a2a-discovery-profile.json
Google identity claims map	https://docs.decionis.com/google-cloud/vertex/decionis-vertex-identity-claims-map.json
Marketplace readiness	https://docs.decionis.com/google-cloud/vertex/decionis-vertex-marketplace-readiness.json
PSC consumer handoff	https://docs.decionis.com/google-cloud/vertex/decionis-vertex-psc-consumer-handoff.json
Trace SRE runbook	https://docs.decionis.com/google-cloud/vertex/decionis-vertex-trace-sre-runbook.json
Billing and Service Control readiness	https://docs.decionis.com/google-cloud/vertex/decionis-vertex-billing-service-control-readiness.json
Go-live checklist	https://docs.decionis.com/vertex-go-live

Distribution bundle

Use these static artifacts when a partner needs an import-ready contract and a compact reference flow.

OpenAPI artifact

The callable API contract for the Vertex authority surface. Import it directly or mirror it into a Google-controlled artifact location.

https://docs.decionis.com/openapi/decionis-vertex-extension-v1.yaml

Tool bundle

A metadata wrapper that lists the Vertex authority operations, required scopes, docs links, and downstream binding posture for partner review.

https://docs.decionis.com/google-cloud/vertex/decionis-vertex-authority-tool-bundle.json

Reference flow

A compact authorize, verify, override, and drift flow for a Gemini agent that needs Decionis authority before Salesforce mutation.

https://docs.decionis.com/examples/decionis-vertex-reference-flow.json

Agent Card

The standalone Agent Card JSON for Cloud Storage upload and Producer Portal validation.

https://docs.decionis.com/google-cloud/vertex/decionis-vertex-agent-card.json

A2A discovery profile

A partner-friendly profile for agent discovery catalogs that need to describe Decionis authority skills without moving policy logic into the agent layer.

https://docs.decionis.com/google-cloud/vertex/decionis-vertex-a2a-discovery-profile.json

Identity claims map

A reference map for turning Google identity-token claims into Decionis actor and Google context fields at the adapter edge.

https://docs.decionis.com/google-cloud/vertex/decionis-vertex-identity-claims-map.json

Marketplace readiness

A reviewer packet that separates shipped controls, optional enterprise hardening, and explicit non-claims for Google Cloud Marketplace review.

https://docs.decionis.com/google-cloud/vertex/decionis-vertex-marketplace-readiness.json

PSC consumer handoff

A private connectivity packet for consumer project allow-listing, endpoint creation, private-path validation, and rollback posture.

https://docs.decionis.com/google-cloud/vertex/decionis-vertex-psc-consumer-handoff.json

Trace SRE runbook

An incident response packet for following one governed action across Google trace headers, Decionis logs, dossiers, metering, token checks, overrides, and drift.

https://docs.decionis.com/google-cloud/vertex/decionis-vertex-trace-sre-runbook.json

Billing readiness

A marketplace billing packet for verified_decision usage, ledger-first reconciliation, optional Service Control export, and replay operations.

https://docs.decionis.com/google-cloud/vertex/decionis-vertex-billing-service-control-readiness.json

Bundle boundary

These artifacts describe the interception and authority contract only. They do not ship policy thresholds, prompt rules, or client-side decision logic.

Verify route

This route is the live Vertex adapter for governed verification requests.

POST/v1/google-cloud/vertex/extensions/verifyAPI key

Normalize agent intent and Google context, invoke Decionis Protocol, and return a governed verdict with Decision Dossier verification links.

Field	Meaning
org_id	Target Decionis workspace UUID.
decision_type	Decision family the workflow should evaluate.
workflow_key	Optional workflow template key when a governed pack is already selected.
system_of_record	Downstream system the agent intends to mutate.
intent	Action metadata and payload proposed by the agent.
google_context	Optional agent, session, project, and principal metadata captured at the adapter edge.

Authority binding

Use this route when a Vertex or Gemini agent is about to call a downstream tool that mutates Salesforce, ServiceNow, SAP, or another system of record.

POST/v1/authority/enforce-and-bindAPI key

Evaluate an exact canonical intent in ENFORCEMENT mode and issue a short-lived execution grant only for an AUTHORITATIVE ALLOW.

Field	Meaning
downstream_target.system	System that will execute the mutation, such as Salesforce or ServiceNow.
downstream_target.operation	Operation the downstream system must bind to the Decionis decision.
downstream_target.required_decision_binding	The exact system and operation are committed into the canonical intent and grant.
binding_ttl_seconds	The intent expiry and grant expiry bound the authority window.
authority_classification	Must be AUTHORITATIVE; OBSERVATIONAL artifacts never execute.
execution_token	Signed grant returned only for execution-eligible ALLOW decisions.

Reference flow

Gemini proposes a refund. Decionis evaluates and binds the exact intent. Salesforce creates the refund only after Decionis atomically revalidates and claims that authority immediately before commit.

Escalation behavior

If Decionis returns ESCALATE, BLOCK, REVIEW_REQUIRED, or an observational result, no execution grant exists. The downstream system stops or hands off for review.

Pre-commit claim

Use this canonical route at the last responsible boundary before the downstream system mutates state.

POST/v1/execution/claim-tokenAPI key

Revalidate signature, exact intent, policy, material signals, Presence evidence, target, correlation, expiry, and atomically consume the single-use nonce.

Check	Meaning
Authority	The grant is Protocol 1.1, AUTHORITATIVE, signed, and scoped to the workspace.
Lease	The returned claim lease is still live at the actual commit boundary.
Nonce	The grant is atomically claimed once; replay is rejected.
Downstream target	The exact canonical target and payload match the action about to commit.
Binding source	Presence is revalidated where required; review evidence does not authorize execution by itself.

Downstream rule

Proceed only when should_execute=true, claim_token is present, and claim_lease_expires_at remains live. valid=true alone is diagnostic and never sufficient.

Override loop

Use these routes when Decionis escalates or holds a Vertex action and the workflow needs a controlled human handoff.

POST/v1/google-cloud/vertex/authority/overridesAPI key

Create an auditable override request tied to a Decision Dossier, Google context, evidence references, agent intent, and downstream target.

POST/v1/google-cloud/vertex/authority/overrides/:overrideId/reviewAPI key

Review the override as action-bound human evidence. Approval does not directly mint execution authority.

State	Downstream behavior
PENDING	Keep the downstream write paused. The override request is now part of the protocol audit trail.
APPROVED	Record action-bound human evidence, then re-evaluate the exact action through the canonical authority path.
REJECTED, ESCALATED, or CANCELLED	No execution token is issued. The downstream tool stops or routes to the next review path.

Override boundary

The override route records Presence evidence tied to the original Decision Dossier. Decionis must freshly re-evaluate the exact action before any execution grant can exist.

Auth posture

Keep identity and authorization explicit at the adapter edge.

Header	Required	Meaning
Authorization	Yes	Bearer org API key with decision:write, decision:, or org: scope.
x-google-identity-token	Optional or required by deployment	Google identity token used for adapter-edge identity proof. Enable or require it with the GOOGLE_CLOUD_VERTEX_OIDC_* env settings.
Idempotency-Key	Optional	Safe replay protection for tool retries or repeated agent calls.
x-cloud-trace-context or traceparent	Optional	Forward Google Cloud Trace or W3C trace context so Decionis logs and metering records can correlate the adapter call with Cloud Logging and Monitoring.

Response debug fields

The adapter response always includes google_identity_verified, google_identity_mode, trace_correlation, regional_posture, metering, and metering_export so partner teams can see whether Google identity proof, trace stitching, locality checks, and Google-shaped usage export were active for the request.

Import flow

Keep the import sequence simple and explicit for a first partner run.

# 1. Download the Decionis OpenAPI artifact
curl -O https://docs.decionis.com/openapi/decionis-vertex-extension-v1.yaml

# 2. Register or mirror the spec in the Google Cloud environment your import flow expects
#    Example: upload the file to your controlled GCS location if your process requires it.

# 3. Configure the extension/tool to call the public Decionis adapter route:
#    https://api.decionis.com/v1/google-cloud/vertex/extensions/verify
#    https://api.decionis.com/v1/authority/enforce-and-bind
#    https://api.decionis.com/v1/execution/claim-token
#    https://api.decionis.com/v1/execution/finalize-token
#    https://api.decionis.com/v1/google-cloud/vertex/authority/overrides
#    https://api.decionis.com/v1/google-cloud/vertex/authority/overrides/<override_id>/review

# 4. Supply a Decionis org API key
#    Authorization: Bearer dcy_org_xxx

# 5. If your deployment enables Google adapter-edge verification, also send:
#    x-google-identity-token: <google_oidc_token>

# 6. Treat the Vertex verify response as OBSERVATIONAL evidence. Consequential
#    execution requires canonical exact-action authority plus a live pre-commit
#    claim at the downstream boundary.

Implementation steps

Use this sequence when a partner is wiring the Vertex adapter into a real Google Cloud or Vertex AI workflow.

Step	What to do	Expected result
1. Issue org credentials	Create or reuse a Decionis org API key with decision:write, decision:, or org: scope for the target workspace.	The caller can authenticate to the Vertex adapter route.
2. Import the OpenAPI spec	Import or mirror the Vertex OpenAPI artifact into the Google-controlled environment your Agent Engine or ADK flow expects.	Vertex treats Decionis as a tool surface, not as a second decision runtime.
3. Point the tool to Decionis	Configure the tool or extension to call https://api.decionis.com/v1/google-cloud/vertex/extensions/verify for observation, then https://api.decionis.com/v1/authority/enforce-and-bind and https://api.decionis.com/v1/execution/claim-token for consequential execution.	Observation remains separate from canonical execution authority.
4. Forward Google context	Send google_context with project_id, location, agent identifiers, and service account or subject metadata when available.	Decionis can record traceable Google execution context around the decision.
5. Enable edge identity verification	Set GOOGLE_CLOUD_VERTEX_OIDC_* env values if you want optional or required Google identity token validation at the adapter edge.	The response shows disabled, optional, or required identity mode plus whether verification succeeded.
6. Set regional posture	Configure GOOGLE_CLOUD_VERTEX_ALLOWED_LOCATIONS, GOOGLE_CLOUD_VERTEX_LOCATION_REQUIRED, and GOOGLE_CLOUD_VERTEX_SERVING_REGION when locality matters.	The response includes regional_posture and can reject disallowed or missing locations.
7. Wire execution gating	Treat Vertex execution_guidance as observational. Submit the canonical exact intent to the Execution Authority Interface in ENFORCEMENT mode.	Vertex provides intelligence, Decionis provides authority, and the downstream system executes only when authority is proven.
8. Keep proof and metering	Store dossier identifiers, verification URLs, trace_correlation, metering, and metering_export with the downstream execution record.	Every governed action keeps proof, traceability, and usage context together.
9. Claim at commit	Before Salesforce, ServiceNow, SAP, or another write-capable tool mutates state, atomically claim and revalidate the grant with the exact intent.	The downstream tool executes only with should_execute=true, a claim token, and a live lease.
10. Wire override review	When a decision escalates or holds, create a Vertex authority override request and review it through the override review route.	Approved human overrides become Presence evidence; a fresh exact-action evaluation remains mandatory.

Runtime env

These are the main runtime controls for the live adapter posture.

GOOGLE_CLOUD_VERTEX_OIDC_AUDIENCES=
GOOGLE_CLOUD_VERTEX_OIDC_ISSUERS=
GOOGLE_CLOUD_VERTEX_OIDC_HEADER_NAME=x-google-identity-token
GOOGLE_CLOUD_VERTEX_ALLOWED_LOCATIONS=
GOOGLE_CLOUD_VERTEX_LOCATION_REQUIRED=0
GOOGLE_CLOUD_VERTEX_SERVING_REGION=
GOOGLE_CLOUD_VERTEX_SERVICE_CONTROL_ENABLED=0
GOOGLE_CLOUD_VERTEX_SERVICE_CONTROL_SERVICE_NAME=
GOOGLE_CLOUD_VERTEX_SERVICE_CONTROL_METRIC_NAME=decionis.googleapis.com/verified_decision
GOOGLE_CLOUD_VERTEX_SERVICE_CONTROL_OPERATION_NAME=decionis.vertex.extensions.verify

Implementation boundary

Do not move policy logic, approval logic, or dossier issuance into Vertex. The extension stays thin by design: it gathers context, calls Decionis, and returns one governed result that downstream systems can trust.

Example call

This is the smallest useful request body for a first Vertex AI validation.

curl -X POST https://api.decionis.com/v1/google-cloud/vertex/extensions/verify \
  -H "Authorization: Bearer dcy_org_xxx" \
  -H "x-google-identity-token: <google_oidc_token>" \
  -H "x-cloud-trace-context: 105445aa7843bc8bf206b12000100000/12345;o=1" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: vertex-verify-1" \
  -d '{
    "org_id": "c65f0510-bb59-48c7-9a73-f3b12338dfaa",
    "decision_type": "TRANSACTION_ROUTING",
    "workflow_key": "finance_transaction_routing",
    "vertical_pack": "finance_transaction_routing",
    "policy_version": "finance-routing-v2",
    "system_of_record": "SAP",
    "amount": 12500,
    "risk_score": 0.18,
    "intent": {
      "action_type": "CREATE_VENDOR_PAYMENT",
      "target_entity": "invoice",
      "target_id": "INV-2048",
      "payload": {
        "invoice_id": "INV-2048",
        "currency": "EUR"
      }
    },
    "context": {
      "region": "europe-west1",
      "business_unit": "procurement"
    },
    "google_context": {
      "agent_id": "vertex-agent-1",
      "agent_session_id": "session-42",
      "tool_call_id": "tool-call-7",
      "project_id": "decionis-labs",
      "location": "europe-west1",
      "service_account_email": "vertex-agent@decionis-labs.iam.gserviceaccount.com"
    }
  }'

Response posture

A successful Vertex verify response returns observational decision evidence, dossier identifiers, public verification URLs, Google identity state, trace correlation, regional posture, and metering. It never authorizes a downstream write.

Canonical execution example

Use the complete exact-intent, authority, pre-commit claim, and finalize example published at /examples/decionis-vertex-bound-execution-client.ts. The legacy Vertex token verification endpoint is retained only for historical signature diagnostics and never returns Protocol 1.1 execution eligibility.

curl -X POST https://api.decionis.com/v1/google-cloud/vertex/authority/overrides \
  -H "Authorization: Bearer dcy_org_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": "c65f0510-bb59-48c7-9a73-f3b12338dfaa",
    "dossier_id": "3fbf8ef1-d83f-454e-b5eb-f820fd1114ff",
    "reason_code": "CUSTOMER_RETENTION_APPROVAL",
    "override_note": "Supervisor review requested from Vertex refund workflow.",
    "evidence_refs": ["gs://evidence/refund-case-500xx000001.json"],
    "google_context": {
      "agent_id": "gemini-agent-1",
      "agent_session_id": "session-refund-1",
      "tool_call_id": "tool-call-refund-1",
      "project_id": "decionis-labs"
    },
    "intent": {
      "action_type": "CREATE_REFUND",
      "target_entity": "case",
      "target_id": "500xx000001"
    },
    "downstream_target": {
      "system": "Salesforce",
      "operation": "CREATE_REFUND",
      "resource_type": "case",
      "resource_id": "500xx000001"
    }
  }'

curl -X POST https://api.decionis.com/v1/google-cloud/vertex/authority/overrides/<override_id>/review \
  -H "Authorization: Bearer dcy_org_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": "c65f0510-bb59-48c7-9a73-f3b12338dfaa",
    "review_outcome": "APPROVE",
    "review_note": "Approved for customer retention.",
    "downstream_target": {
      "system": "Salesforce",
      "operation": "CREATE_REFUND",
      "resource_type": "case",
      "resource_id": "500xx000001"
    },
    "binding_ttl_seconds": 180
  }'

Verification steps

Use this checklist to prove the Vertex integration is working end to end after deployment.

Check	How to validate	Success signal
Adapter call	Send a direct POST to /v1/google-cloud/vertex/extensions/verify before validating through Vertex itself.	HTTP 200 with status, outcome, policy_version, verification, trace_correlation, regional_posture, metering, and metering_export in the response.
Execution authority	Inspect the response and downstream behavior.	The Vertex response is observational; the downstream tool does not act on execution_guidance.
Bound execution	Call /v1/authority/enforce-and-bind with the canonical exact intent in ENFORCEMENT mode.	Only AUTHORITATIVE, execution-eligible ALLOW responses include a signed grant.
Pre-commit claim	Call /v1/execution/claim-token immediately before the downstream write.	Proceed only with should_execute=true, a claim token, and a live claim lease; any mismatch fails closed.
Override review	Create a Vertex authority override for an escalated or held dossier, then review it.	Approved reviews record Presence evidence but issue no grant; exact-action re-evaluation remains required.
Decision Dossier proof	Open verification.verification_url or verification.verification_page_url from the response.	A real public verification page or API response resolves for the returned dossier.
Idempotency	Repeat the same request with the same Idempotency-Key.	The response stays stable and the replay path does not create a new uncontrolled action.
Google identity verification	When OIDC is enabled, call once with a valid token and once with a missing or invalid token.	Valid calls return google_identity_verified=true. Invalid or missing required tokens return 401.
Regional posture	Call once with an allowed google_context.location and once with a disallowed location when the allowlist is active.	Allowed locations return location_accepted=true. Disallowed or missing required locations return 400.
Metering ledger	List metering records through the org-scoped operator route after a successful verification.	A verified_decision event exists for the adapter call.
Service Control export	When enabled, inspect metering_export in the response and the recorded metering event.	metering_export.status is reported, or failed states are replayable without rerunning the business decision.
Google-native observability	Inspect Cloud Logging / Monitoring resources after live traffic reaches the adapter.	The Vertex log metrics, dashboard, and alert policies exist and begin receiving data.

Verification response fields

These response fields should be present on a healthy adapter call.

status
outcome
policy_version
verification
google_identity_verified
google_identity_mode
trace_correlation
regional_posture
metering
metering_export
execution_guidance
bound_execution
execution_token

Operator validation path

Use these routes after the first successful call to validate usage export and replay behavior.

GET https://api.decionis.com/v1/orgs/<org_id>/google-cloud/vertex/metering
POST https://api.decionis.com/v1/orgs/<org_id>/google-cloud/vertex/metering/<event_id>/replay-service-control

Recommended validation order

Validate the adapter directly first, then import the tool into Vertex, then verify Google identity and regional controls, and only after that validate Service Control export and Google-native dashboards. That order keeps control-plane failures separate from marketplace or enterprise hardening concerns.

Production rollout checklist

When the adapter is already passing verification, use the dedicated go-live page for launch readiness, rollback posture, and Google-native validation steps.

https://docs.decionis.com/vertex-go-live

Operational posture

What is already implemented versus what remains enterprise hardening.

Area	Status	Current posture
Google OIDC / WIF bridge	Available now	The adapter can validate a Google identity token from x-google-identity-token, enforce audiences, and mark the response as disabled, optional, or required.
Cloud Logging / Monitoring-friendly telemetry	Available now	Structured request logs include Google project, location, service account or subject, policy version, verdict, trace correlation, and metering labels so Google-native observability can ingest them cleanly.
Alerting baseline	Available now	Terraform can provision Monitoring alert policies for identity or location failures and sustained blocked or hold decision surges so the raw metrics turn into operational response.
Regional posture	Available now	The adapter can require or allowlist google_context.location and returns regional_posture in the response so partner systems can verify the serving region and whether the requested location was accepted.
Commercial metering seed	Available now	Each adapter response includes metering.unit=verified_decision and metering.count=1, and Decionis persists the event into a metering ledger for downstream billing or service-control reporting.
Canonical execution authority	Available now	The canonical authority route issues a short-lived exact-action grant only for an authoritative ALLOW; claim and finalize bind it through the downstream attempt.
Google Service Control usage export	Available now	The adapter can export the verified_decision unit to Service Control with ADC / Workload Identity while keeping the Decionis metering ledger as the reconciliation source of truth.
Marketplace billing readiness	Available now	The public billing readiness packet documents the verified_decision billing unit, ledger-first reconciliation, Service Control replay, and non-goals for marketplace review.
Private Service Connect producer path	Available now	The GKE deployment now supports an opt-in PSC producer path with an internal API service, dedicated PSC NAT subnet, and a GKE ServiceAttachment manifest. Consumer project approval and endpoint wiring remain the next enterprise networking increment.
Regional endpoints and CMEK	Partially available	Regional posture is live in the adapter, and Terraform can now provision KMS keys for Artifact Registry and GKE node boot disks. Broader per-service CMEK guarantees still remain deployment-specific hardening rather than a blanket product claim.

Operator endpoints

These org-scoped routes help operators inspect and replay Google-native usage export without changing the governed decision contract.

GET/v1/orgs/:orgId/google-cloud/vertex/meteringAPI key

List recent Vertex metering events and Service Control export posture for an org.

POST/v1/orgs/:orgId/google-cloud/vertex/metering/:eventId/replay-service-controlAPI key

Replay Service Control export for a recorded Vertex metering event without rerunning the business decision.

POST/v1/google-cloud/vertex/authority/drift/eventsAPI key

Submit override, downstream refusal, or model-intent drift signals for Decision Dossier and Protocol correlation.

POST/v1/google-cloud/vertex/authority/execution-tokens/verifyAPI key

Historical signature diagnostic only; legacy Vertex tokens are never Protocol 1.1 execution-eligible.

POST/v1/google-cloud/vertex/authority/overridesAPI key

Request a controlled human override for a Vertex authority decision.

POST/v1/google-cloud/vertex/authority/overrides/:overrideId/reviewAPI key

Review a Vertex authority override as Presence evidence without issuing execution authority.

Why replay exists

The governed decision should not fail just because Google-native billing or reporting had a transient problem. Replay lets operators re-export usage from the Decionis metering ledger after fixing service name, IAM, or consumer project configuration.

Next hardening

These are the remaining enterprise follow-ons after the current adapter path is working.

Next step	Why it matters
CMEK-backed deployment posture	Extends the shipped KMS baseline beyond Artifact Registry and GKE boot disks when a customer deployment requires broader data-at-rest coverage.
Marketplace submission polish	Package customer-specific pricing copy, screenshots, contract language, and enterprise readiness evidence around the shipped runtime and review packets.

On this page

config.toml

Gate an agent (MCP)

[mcp_servers.decionis]
command = "npx"
args = ["-y", "@decionis/mcp"]
required = true

# APPROVE continues. REJECT, REVIEW and
# ESCALATE stop the call before it runs.

Tool calls are evaluated before they run; missing policy denies by default.

Browser sandbox · deterministic · nothing leaves this page. The sample above runs against the live API with your key.