API versioning
The two planes are versioned differently, on purpose.
| Plane | Mechanism | Current |
|---|---|---|
| Management | ?api-version= query parameter, date-based |
2026-08-30 |
| Product | In the path | /v1.0 |
| Protocol | By the defining standard | Not DiligenceID's to version |
Management: date versions
GET /management/issuers?api-version=2026-08-30
Required on every Management request.
Date versioning suits configuration APIs: they accumulate small additions, and a caller wants to pin the exact shape they were written against and keep working when a newer one ships. A version is a date because that is what a caller needs to know — when this contract was fixed.
Two distinct failures:
| Detail code | Meaning | Fix |
|---|---|---|
MissingApiVersionParameter |
You did not send one | Add it |
UnsupportedApiVersionValue |
This deployment does not serve that one | Use a supported version |
Both are 400 with error.code of validation_error and error.target of api-version; the codes above
appear in error.details[].code. They are separate codes because collapsing them makes the second look like a
typo.
Pin the version. Do not compute it, and do not send "the latest" — the point of pinning is that a new version shipping does not change your behaviour.
Product: path versions
POST /v1.0/credentials/issuance
Runtime callers hard-code URLs and need them stable. A breaking change deserves a visibly different path rather than a parameter someone might not have set.
/v1.0 is canonical. /v1 is a supported compatibility alias — the same handler, the same behaviour,
including the same idempotency identity, so a retry that started on one and finished on the other still
deduplicates correctly.
What is additive
These can happen within a version and your client must tolerate them:
- a new field in a response
- a new optional request field
- a new operation
- a new value in an enum you receive
Ignore unrecognised response fields. A client that rejects them breaks on the first additive change.
Be careful with enums you receive: a new status value should not crash your switch. Handle the default.
What is breaking
These require a new version and an announced deprecation:
- removing a route, operation or response field
- renaming an operation ID — that is a rename in the specification, but a deletion and an addition to a generated SDK, and their code stops compiling
- making an optional request field required
- changing a field's type
- removing an enum value
- requiring a narrower scope
All of these are checked automatically against the previous released contract; a change that would break an existing integration fails the build.
Compatibility aliases
Management operations also answer on /v1.0 and /v1, where they originally shipped. They are not described
in the published specifications — publishing them would double every operation in the reference and in every
generated SDK.
A caller on a Management alias sends no api-version and therefore has no version pinning. That means they
are not protected from a future Management contract change the way a /management caller is. It is a reason to
move, and there is no announced removal date.