API binding

When to use API Passport binding

• You expose an authorised API surface that other parties or agents will integrate against.
• A buyer, agent, or platform needs to verify the API origin and OpenAPI spec before integration.
• You need machine-checkable evidence that the spec at runtime matches what was declared.

One API Passport = one authorised API surface

Same API across regions vs different APIs

• Same logical API exposed in multiple regions → sub-bindings of one API Passport.
• Different logical APIs (different surface, different scope, different contract) → separate API Passports.
• A v1 / v2 of the same API can share an API Passport with version metadata; a fundamentally different surface needs its own.

What the API binding records

• API origin for the authorised surface.
• OpenAPI spec URL and canonical spec hash.
• Endpoint or scope state where provided by the operator.
• Regional aliases as sub-bindings of the same API Passport.
• Agent Credential dependency when an agent is the authorised caller.

OpenAPI x-ecz-id 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

OpenAPI extension fields

Failure states

• OpenAPI hash changed — Resolver projects MISMATCH until a new binding is issued for the new spec.
• Origin mismatch — request appears from an origin not listed in the binding; verifier should fail closed.
• Stale scope map — declared endpoints/scopes no longer match the live spec; treat as MISMATCH.

Resolver proof

Resolver projects BOUND state for the API Passport only after Backend/Core verification. Developer Gateway does not validate live API traffic and does not claim the API is safe, compliance-guaranteed, or approved.