Discovery metadata · Not proof

OpenAPI x-ecz-id Extensions

How to declare ECZ-ID Agent Credential and API Passport references inside OpenAPI documents using the one x-ecz-id extension object.

The x-ecz-id object

Its fields are defined once, in the canonical reference at /bindings/openapi-x-ecz-id/.

x-ecz-id — one object inside OpenAPI info: operator_ecz_id, api_passport_id, api_origin, spec_hash and resolver_url, with optional fields listed in the canonical reference
agent_credential_id inside x-ecz-id — used when the OpenAPI document also declares the calling agent

YAML example

openapi.yaml

openapi: 3.1.0
info:
  title: Example Support API
  version: "1.0.0"
  x-ecz-id:
    operator_ecz_id: ECZ-GB-EXAMPL
    api_passport_id: ECZ-GB-EXAMPL::API-DEF456
    api_origin: https://api.example.com
    spec_hash: sha256:<hash-of-canonical-spec>
    resolver_url: https://resolver.ecocitizenz.org/p/ECZ-GB-EXAMPL/API/DEF456
    agent_credential_id: ECZ-GB-EXAMPL::AGENT-ABC123
paths:
  /tickets:
    get:
      summary: List tickets

JSON example

openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "Example Support API",
    "version": "1.0.0",
    "x-ecz-id": {
      "operator_ecz_id": "ECZ-GB-EXAMPL",
      "api_passport_id": "ECZ-GB-EXAMPL::API-DEF456",
      "api_origin": "https://api.example.com",
      "spec_hash": "sha256:<hash-of-canonical-spec>",
      "resolver_url": "https://resolver.ecocitizenz.org/p/ECZ-GB-EXAMPL/API/DEF456",
      "agent_credential_id": "ECZ-GB-EXAMPL::AGENT-ABC123"
    }
  }
}

Forbidden fields and content

No secrets
No keys or token material
No auth headers or example bearer tokens
No prompts or model system messages
No source code in extension fields
No user data in extension fields
No claims of approval, certification, or partnership

Stale metadata warning

Extension fields can drift from the underlying credential reality. Treat them as discovery hints. Current proof must be checked via Resolver.

Open Resolver ↗API Passport docs →

ECZ-ID separates setup, verification state, and public proof. Developer Gateway documents setup paths and verifier guidance. TrustOps handles setup. Resolver remains the public proof surface. Re-check before reliance. Local policy decides.