API planes
DiligenceID has four groups of endpoints. They differ in who calls them, how they are versioned, and what guarantees they carry — which is why they are separated rather than being one API with a mixed URL space.
| Plane | Base path | Versioning | Auth | Status |
|---|---|---|---|---|
| Management | /management |
?api-version=2026-08-30 |
API key | Stable |
| Product | /v1.0 |
In the path | API key | Stable |
| Protocol | Standards-defined | By the standard | Per the standard | Protocol-defined |
| Internal / BFF | /api/* |
None | Session | Internal — not public |
Management
Configures resources: organisations, issuers, credential configurations, verification policies. These are things you set up once and change occasionally.
GET /management/issuers?api-version=2026-08-30
Authorization: ApiKey did_test.abc.xyz
Management responses use a resource envelope — identity, concurrency token and audit stamps in the same place
for every resource, with the resource's own fields under properties:
{
"id": "/management/issuers/workforce",
"name": "workforce",
"type": "DiligenceID/issuers",
"etag": "\"AAAAAAAAB9E=\"",
"properties": { "displayName": "Workforce Credentials", "status": "Active" },
"systemData": { "createdAt": "2026-08-30T04:11:02Z", "lastModifiedAt": "2026-08-30T04:12:44Z" }
}
Collections return { "value": [...], "nextLink": null }.
Every Management request must name an API version. See API versioning.
Management API reference · concept
Product
Runs transactions: issuing, reading status, revoking, verifying. These are things you do continuously, often on the critical path of someone's actual transaction.
POST /v1.0/credentials/issuance
Authorization: ApiKey did_test.abc.xyz
Idempotency-Key: order-4417
Product responses use { "data": ... }. Mutating operations accept Idempotency-Key, which is what makes a
retry safe. See idempotency.
Product API reference · concept
Protocol
Endpoints defined by OpenID4VCI, OpenID4VP, SD-JWT VC status lists and issuer metadata discovery. Wallets and verifiers call these; your server generally does not.
Their shape is dictated by the standards that define them, so DiligenceID does not version them, does not wrap them in its own envelope, and does not add its own headers to them. Doing any of that would make a compliant wallet fail against a compliant issuer.
Internal / BFF
/api/* serves the DiligenceID admin application through a backend-for-frontend using session cookies. It is
not part of the public API, is not described in either published specification, and is not versioned for
external callers. It changes without notice.
If a piece of functionality appears to exist only there, treat that as a gap to raise rather than a route to integrate against.
Why the separation
They change at different rates. Adding a field to an issuer configuration and changing how issuance behaves have different blast radii. A single version number would force one to wait for the other.
They are versioned differently for good reasons. Management is date-versioned because configuration contracts accumulate small additions and callers want to pin a known shape. Product is path-versioned because runtime callers need a stable URL they can hard-code, and a breaking change there deserves a visibly different path.
Protocol endpoints are not ours to version. They belong to the standards bodies that define them.
Mixing them hides the boundary. When configuration and runtime share a URL space, it stops being obvious which calls belong in a deploy pipeline and which belong on a request path.
Which do I need?
| If you are… | Use |
|---|---|
| Setting up issuers and credential types | Management |
| Issuing credentials from your application | Product |
| Verifying credentials presented to you | Product, plus a verification policy from Management |
| Building a wallet | Protocol |
| Building an admin UI on top of DiligenceID | Management — not /api/* |
Most integrations use Management once during setup, then Product continuously. The two SDKs are separate for the same reason.
Compatibility
/v1 predates the split, and Management operations were originally reachable on /v1.0. Both still work, and
return exactly the bodies they always did — an alias is the same handler, not a reimplementation.
They are deliberately absent from the published specifications. Publishing them would double every operation in the reference and in every generated SDK, for routes nobody should newly adopt.
Move to /management and /v1.0 when convenient. There is no announced removal date for the aliases; note
that a caller on a Management alias gets no version pinning, so they are not protected from a future contract
change the way a /management caller is.