OpenAPI x-ecz-id reference
Canonical OpenAPI 3.1 extension fields that bind an API spec to its operator’s Parent ECZ-ID (operator_ecz_id), an API Passport, and an optional Agent Credential, and instruct relying parties to re-check before reliance.
Purpose
The x-ecz-id OpenAPI extension lets an API publisher declare which ECZ-ID parent identity, API Passport, and optional Agent Credential the API is associated with, where the canonical Resolver projection lives, and that relying parties must re-check current state before reliance. The extension is discovery only. Resolver remains the public proof surface for current state.
Canonical reference
This page is the one reference for x-ecz-id. Every other x-ecz-id example on this site is generated from the same machine-readable registry, /schemas/declaration-contracts.json.
- x-ecz-id is one object inside OpenAPI info. A string value is not a declaration.
- The operator is operator_ecz_id: the Parent ECZ-ID of the accountable operator, as ECZ-ID Core and the Resolver name it.
- x-ecz-api-passport, x-ecz-agent-credential and x-ecz-reverify-before-reliance are retired. Nothing in ECZ-ID Core, the Resolver or the verifier reads them; use api_passport_id, agent_credential_id and recheck_before_reliance inside x-ecz-id.
Fields
| Field | Required | Purpose |
|---|---|---|
| operator_ecz_id | yes | Parent ECZ-ID of the operator (org / publisher). |
| api_passport_id | yes | Canonical API Passport ID issued by ECZ-ID Core. |
| api_origin | yes | Authorised origin that serves this API. |
| spec_hash | yes | SHA-256 of the canonical OpenAPI document. |
| resolver_url | yes | Public Resolver projection URL for this passport. |
| agent_credential_id | no | Optional agent credential when the API is operated by a named agent. |
| recheck_before_reliance | recommended | Boolean — instructs relying parties to re-query the Resolver before relying on this API. |
| policy_mode | recommended | Local hint such as require_resolver_ok / require_resolver_ok_recent — does not bind the relying party. |
Example
openapi: 3.1.0
info:
title: Example Support API
version: "1.0.0"
x-ecz-id:
operator_ecz_id: ECZ-GB-XXXXXX
api_passport_id: ECZ-GB-XXXXXX::API-2Q7X9B
api_origin: https://api.example.com
spec_hash: sha256:<hash-of-canonical-spec>
resolver_url: https://resolver.ecocitizenz.org/p/ECZ-GB-XXXXXX/API/2Q7X9B
agent_credential_id: ECZ-GB-XXXXXX::AGENT-4F9Q2A
recheck_before_reliance: true
policy_mode: require_resolver_ok_recentDeclaration, not binding proof
A declaration names its operator with operator_ecz_id. A binding proof is a separate step: when ECZ-ID Core opens a binding challenge, its proof instructions give the exact document to publish, with parent_ecz_id, binding_id and challenge. Copy that document verbatim. Never write those fields by hand, and never rename operator_ecz_id to parent_ecz_id in a declaration.
What x-ecz-id does NOT do
- It does not assert that the API is risk-free, vetted as compliant, sanctioned for any specific use, or underwritten.
- It does not bypass the relying party’s local policy.
- It does not replace the Resolver — relying parties still re-check current state at the Resolver URL.
- It does not carry secrets — never embed API keys, OAuth tokens, private keys, or webhook secrets.
- do_not_infer and no_safety_or_approval_inference: presence of the extension does not imply any safety, compliance, or approval status.
Setup path
API Passports are issued by ECZ-ID Core and set up through TrustOps. Developer Gateway is documentation only. After setup, the spec hash and Resolver projection are owned by ECZ-ID Core and visible on the Resolver.
Live proof posture
Live public binding projection for this documentation surface has not yet been independently proven. These docs describe the documented model only.