API documentation

Vertex AI extension quickstart

Use Decionis as a governed verification tool inside Vertex AI workflows without moving decision logic into the model layer. The current adapter route normalizes agent intent, invokes Decionis Protocol, and returns a governed verdict plus Decision Dossier proof that downstream tools can verify before write actions proceed.

Overview

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

Decision boundary

Vertex AI is the distribution surface. Decionis Protocol remains the execution-time decision 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://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	/docs/api
Auth posture	/docs/auth
Decision Dossier verification	/docs/decision-dossier
Generic quickstart	/docs/quickstart
Go-live checklist	/docs/vertex-go-live

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.

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://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

# 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. Use the response dossier links, google_identity flags, trace_correlation,
#    regional_posture, metering, and metering_export fields to gate the downstream write action

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.	All agent verification calls go through the Decionis adapter route.
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	Make the downstream action proceed only when execution_guidance.allowed is true and the returned disposition matches the intended workflow policy.	Vertex distributes the request, but Decionis Protocol remains the execution-time authority.
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.

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 response returns the governed status, the underlying Protocol outcome, the current policy version, the dossier identifiers, public verification URLs, Google identity verification state, normalized trace_correlation, regional posture, the verified_decision metering envelope, optional Service Control export status, and execution guidance such as EXECUTE, ESCALATE, BLOCK, or HOLD.

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.
Decision authority	Inspect the response and downstream behavior.	The downstream tool acts on execution_guidance, and the decision is backed by a Decionis dossier rather than a model-only judgment.
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

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.

/docs/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.
Google Service Control usage export	Available as an opt-in hardening path	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.
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.

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
Private Service Connect	Completes consumer project wiring, approval playbooks, and endpoint rollout on top of the shipped producer-side PSC path.
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.
Service Control / enterprise metering	Builds on the shipped opt-in export so marketplace and enterprise reporting can become replayable, monitored, and contract-bound.
Deeper Cloud Trace and SRE export	Builds on the shipped trace_correlation and alerting baseline with richer trace linkage, routing, and operator runbooks without replacing the Decionis ledger or Decision Dossier proof model.

Loading…

Decionis API Reference

Base URL: https://api.decionis.com/v1

Quickstart Main site Contact