OpenAPI x-ecz-id reference
Canonical OpenAPI 3.1 extension fields that bind an API spec to a parent 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.
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 Backend/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_recentWhat 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 Backend/Core and set up through TrustOps. Developer Gateway is documentation only. After setup, the spec hash and Resolver projection are owned by Backend/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 code-proven and test-proven model only.