OpenAPI

DiligenceID publishes two canonical specifications, one per API plane. Both are generated from the running application — the implementation is authoritative and these files are its published form.

What each one contains

Management configures DiligenceID resources: organisations, issuers, credential configurations and verification policies. Every operation requires a supported api-version.

Product performs runtime transactions: issuing credentials, reading status, revoking, running verifications, verification sessions and issuance transactions.

Neither document describes the compatibility routes. Management operations remain reachable on /v1.0 and /v1 for existing clients, and the Product API remains reachable on /v1, but those are aliases of a canonical operation rather than contracts of their own — publishing them would double every operation in the specification, in generated reference documentation and in generated SDKs.

Neither document describes the internal /api/* administrative surface, the BFF routes, or protocol endpoints. Protocol endpoints (/.well-known/*, OID4VCI, OID4VP, status lists) are governed by the standards that define them and are documented separately.

Fetching them from a running instance

curl -sS "$DILIGENCE_BASE_URL/swagger/management/swagger.json" -o management.json
curl -sS "$DILIGENCE_BASE_URL/swagger/public-v1/swagger.json" -o v1.0.json

Interactive documentation is at $DILIGENCE_BASE_URL/swagger.

Regenerating the committed files

The files in this directory are checked against the running API by OpenApiSnapshotTests. That test fails when the API and the committed specification disagree, which is what stops a contract change reaching callers without anyone reviewing it.

After an intentional contract change:

dotnet test --filter "FullyQualifiedName~OpenApiSnapshotTests" -e DILIGENCEID_UPDATE_OPENAPI_SNAPSHOTS=1

Then review the diff. A specification changing is not automatically wrong; it changing unnoticed is.

Both files are written with sorted keys and consistent indentation so a diff shows contract changes rather than key-ordering noise from the generator.

Operation IDs are contract

Every operation has a stable Resource_Action identifier — Issuers_Create, Credentials_Issue, VerificationPolicies_Suspend. Generated SDK method names come from these, so changing one is a breaking change rather than a rename. A contract test enforces presence, uniqueness and the naming convention.

Generating a client

npx @openapitools/openapi-generator-cli generate \
  -i v1.0.json -g typescript-fetch -o ./diligenceid-product-client

A generated client handles serialisation. It does not handle retries, idempotency keys or webhook signature verification — see idempotency and webhooks.

Officially supported SDKs are planned and not yet available. There is no sdk/ directory in this repository yet.

Versioning

Product is versioned in the path. /v1.0 is canonical; /v1 is a supported compatibility alias. Additive changes are made in place; a breaking change requires a new version with an announced deprecation.

Management is date-versioned by query parameter. 2026-08-30 is the only supported version today. A request without api-version is rejected with MissingApiVersionParameter; one naming a version this deployment does not serve is rejected with UnsupportedApiVersionValue — deliberately distinct, because the two need different fixes.

Write clients that ignore unrecognised response fields.