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 x-ecz-id family of extensions.

Supported extension keys

x-ecz-id — object containing operator_ecz_id, api_passport_id, manifest_url, resolver_url
x-ecz-api-passport — short identifier for the authorised API surface
x-ecz-agent-credential — 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
    manifest_url: https://example.com/.well-known/ecz-agent.json
    resolver_url: https://resolver.ecocitizenz.org/p/ECZ-GB-EXAMPL/API/DEF456
  x-ecz-api-passport: ECZ-GB-EXAMPL::API-DEF456
  x-ecz-agent-credential: 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",
      "manifest_url": "https://example.com/.well-known/ecz-agent.json",
      "resolver_url": "https://resolver.ecocitizenz.org/p/ECZ-GB-EXAMPL/API/DEF456"
    },
    "x-ecz-api-passport": "ECZ-GB-EXAMPL::API-DEF456",
    "x-ecz-agent-credential": "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.