The subject
The API surface, described and bound
One logical API keeps one identity while its base URL, its version path, its environments and the gateways in front of it all change. Each of those is a binding against the identity. None of them is a second API.
One identity
What one API Passport identifies
The authorised logical surface
The API as your organisation authorises and operates it — the thing a caller means when they say “your payments API”. It is the subject, and it is what the ECZ-ID names.
Where the line falls
Versions, environments, base URLs and gateways of that API are not separate Passports. A second distinct API surface is a second Passport — the test is whether a caller would reasonably describe it as a different API, not whether it runs on different infrastructure.
The base origin
A base URL is where the API answers, not what it is
The base origin is recorded as a binding, normalised without its version segment: a trailing version segment is a binding, not part of the subject. Moving from one major version to the next adds a binding and retires another. It does not mint an identity.
The same is true in the other direction. A staging origin, a regional alias and a partner-facing hostname can all be bound to the same API, which is exactly what makes the record worth reading: it is the only place those are stated to be the same thing by the organisation that operates them.
The domain an origin answers on can be proved through a Domain /.well-known file or a DNS TXT record. Only a binding completed through a live proof method shows control of that asset, and only as of its Last verified time. A declared binding records the relationship and where it was learned. Neither grants authority.
The description
An OpenAPI document describes the API; it is not the API
The document as a binding
The URL of the OpenAPI description you host is recorded against the identity, so a reader who has the description can reach the record, and a reader who has the record can reach the description.
The identifier inside the document
The ECZ-ID sits in the document's own info block as OpenAPI info.x-ecz-id, alongside fields that are already there. It is the API family's own live proof method, and the one that lives inside the document: ECZ-ID verification reads it from the description you host. Nothing about the API's behaviour changes.
Other bindings an API has
A webhook endpoint you publish and the JWKS URI your tokens are checked against are each recorded in their own right: on a domain proved through a Domain /.well-known file or a DNS TXT record, or as declared bindings with where they were learned.
What none of them says
No binding says the description is accurate, the endpoint is reachable, or the API is secure. It says a relationship was declared or proved, and when it was last checked.
The exact field names, the normalisation rules and the schemas behind them belong to the Developer Gateway, which keeps them current. Open the Developer Gateway (opens in a new tab)
Who calls it
Increasingly, the caller is a machine with its own identity
An agent calling your API is a separate subject with its own operator and its own Passport. So is the SDK it uses, and so is the workload that serves your API. Four identities, four operators, four records — and the value is precisely that they are not collapsed into one.
Authorisation stays where it already is. OAuth and your gateway decide what a caller may do; the Passport publishes which API it is and who operates it, to a reader with no access to either.
Where next
Keep going with ECZ-ID API.
- ProductsEvery API product and service, each with its own page.Open
- The free API PassportWhat it establishes, what it never says, and how it is issued.Open
- Verify an ECZ-IDRead a live record on the public Resolver — no account, no key.Open
- Build and integrateAPI binding on the Developer Gateway.Open (opens in a new tab — developers.ecocitizenz.com)