ECZ-ID API Passport Technical Reference

• CANONICAL IDENTITY

  The persistent API ECZ-ID for the logical interface being represented.

• EXTERNAL SURFACES

  URLs, gateways, provider-native IDs, descriptions and environments remain bindings/context.

• REPRESENTED RELATIONSHIP

  The record may publish the organisation/Parent claiming responsibility for the API or relevant operator/service relationship where supported.

• NOT UNIVERSAL ASSURANCE

  The presence of that relationship does not prove every organisational assertion or runtime control.

• CHANGE HANDLING

  If the responsible organisation changes, use the canonical control path and re-check the resulting public proof.

• DUPLICATE HANDLING

  Do not create a replacement API identity solely because organisation/account access changed.

• ENDPOINT / BASE URL

  Public or private address used to reach the API where supported.

• GATEWAY / PROVIDER ID

  API gateway, cloud resource or provider-native identifier as contextual binding.

• OPENAPI / DESCRIPTION

  Machine-readable or human-readable interface description where supported.

• SERVICE / WORKLOAD

  Relationship to the service or workload the API fronts or represents.

• ENVIRONMENT / VERSION

  Production/staging, version or release context where supported.

• REPOSITORY / DOCUMENTATION

  Supporting source or documentation references where appropriate.

• STATE EXAMPLES

  Environment, version, lifecycle status, availability/degradation context or other supported point-in-time state.

• FRESHNESS POLICY

  Choose re-resolution frequency according to how quickly relevant endpoint, version, evidence or operator context can change.

• MISSING STATE

  Treat required absent state as not established.

• MISMATCHED STATE

  If environment/version does not match the intended target, challenge or deny according to policy.

• EVALUATE EACH REFERENCE

  Source · scope · freshness · what claim it actually supports.

• DO NOT INFER

  Presence of evidence does not prove unrelated behaviour, security posture or operational correctness.

• OPENAPI EXAMPLE

  An OpenAPI binding can support interface-description context; it does not prove every runtime behaviour matches the document.

• PROVIDER-ID EXAMPLE

  A cloud resource binding can support association to that provider object; it does not become canonical identity authority.

• PASSPORT LAYER

  Target identity, organisation, bindings, state, evidence and supported authority/context where present.

• AUTHORIZATION LAYER

  Caller authentication, scopes/roles, gateway policy, application policy and action-specific permission.

MACHINE-READABLE ROUTE

GET https://api.ecocitizenz.com/api/p/{ecz_id}.json

• CONSUMER BEHAVIOUR

  Parse only fields actually returned; check family/object and context relevant to your decision.

• FAILURE BEHAVIOUR

  Distinguish not-found, missing evidence, mismatch and network/client failure. Do not fabricate fallback identity.

• DO NOT INFER

  Do not infer authentication, permission or safety from the Passport alone.

• DO RE-RESOLVE

  Re-resolve when endpoint, state, evidence or consequence requires current proof.

• CALLING SIDE

  Agent / service / workload / organisation identity, responsibility and supported action-specific authority context where separately represented.

• API SIDE

  API ECZ-ID, responsible organisation, endpoint/description bindings, current state and evidence.

• EXAMPLE

  An agent resolves the API Passport before invoking a consequential endpoint, then authenticates and presents the permissions required for that specific operation.

• BENEFIT

  The target identity remains independently re-checkable even when the endpoint or gateway changes.

• SAME LOGICAL API

  A production endpoint moves gateway/provider or version while remaining the same intended service interface → preserve ECZ-ID and update bindings/state where appropriate.

• DIFFERENT LOGICAL OBJECT

  A materially distinct API/service interface with different responsibility or object boundary may legitimately need its own Passport.

• CONSUMER CHECK

  Confirm the returned environment/version is appropriate for the intended interaction.

• OPERATOR CHECK

  Keep supported environment/version bindings and evidence current through the canonical control plane.

• TYPICAL MUTATIONS

  Base URL · gateway · OpenAPI/description · provider ID · environment/version · evidence · organisation relationship · published state.

• TYPICAL NON-MUTATION

  The canonical API ECZ-ID remains stable when those contextual elements change for the same logical API.

• NOT FOUND

  Confirm identifier and official Resolver route; do not create a fallback identity in the caller.

• FAMILY/OBJECT MISMATCH

  Reject or challenge if the record is not the API object expected.

• MISSING BINDING/EVIDENCE

  Treat it as absent; do not infer from historical configuration or marketing copy.

• STALE STATE

  Re-resolve or require fresh evidence before proceeding when consequence demands it.

• NETWORK/CLIENT FAILURE

  Distinguish inability to fetch proof from proof that the API identity is invalid.

• AUTHENTICATION FAILURE

  Handle in the API auth layer; it is not proof the Passport identity is wrong.

• OBJECT

  Logical API/service interface

• CANONICAL ID

  Persistent API ECZ-ID

• PUBLIC PROOF

  ECZ-ID Resolver

• MACHINE ROUTE

  GET /api/p/{ecz_id}.json

• RESPONSIBILITY

  Parent/organisation context where supported

• BINDINGS

  Endpoint, gateway/provider IDs, OpenAPI/description, service refs

• STATE

  Point-in-time published context where supported

• AUTHORITY

  Action-specific context where present; never blanket permission

• AUTH

  Separate API authentication/authorization layer

• FAILURE

  Do not infer missing proof; fail safely according to consequence

• OPERATOR OUTCOME

  Maintain one canonical identity while API infrastructure and evidence evolve.

• CONSUMER OUTCOME

  Counterparties can continue to re-check current public proof rather than depending on stale integration assumptions.