OpenAPI reference

DotID exposes public REST APIs as OpenAPI 3.1 specifications through the public APaaS API gateway. This page is your jumping-off point for external developer schemas and generated clients.

Live reference

The public API reference is an aggregated, read-only Stoplight Elements page generated from DotID’s real service OpenAPI documents and the public capability→route mapping:

The reference is browsable — schemas, status codes, and examples — but does not send live requests. It is regenerated from the running services’ specs on every docs deploy, so it always tracks the deployed API.

Each DotID service also publishes a service-local OpenAPI document at the standard springdoc path /v3/api-docs (JSON) or /swagger-ui.html (interactive UI). Those service-local paths are internal implementation details and are not reachable through the public gateway; use the published reference above.

Identity API

The public Identity API is reached through the public API gateway. Public routes use gateway capability prefixes only; internal service controller paths are implementation details.

  • /identity/v1/accounts/{accountId}/service-users... — non-human service users.

  • /identity/v1/accounts/{accountId}/iam-policies... — policies.

  • /identity/v1/accounts/{accountId}/credentials... — access keys (create, list, get, rotate, delete).

  • /identity/v1/organizations... — organizations, OUs, SCPs.

  • /identity/v1/organizations/{orgId}/identity-center/... — Identity Center workforce users and groups.

  • /identity/v1/organizations/{orgId}/permission-sets... — permission sets.

  • /identity/v1/organizations/{orgId}/account-assignments... — Identity Center account assignments.

Each endpoint’s request schema, response schema, and error catalog is fully documented in the live spec.

Audit service spec

The public Audit API is exposed through the gateway’s /audit/ prefix:

  • /audit/v1/me — the caller’s audit profile.

  • /audit/v1/accounts/{accountId}/events — paginated query over one account’s audit log.

  • /audit/v1/events/{eventId} — single-event fetch by event ID.

Use this to investigate what DotID decided and why. Every PDP decision and every trust-policy mutation produces an audit event.

Versioning

All DotID APIs version through the URL path (/v1/, future /v2/, etc.). The platform does not use Accept-header versioning. Versions are stable: a v1 endpoint may add optional response fields but will not change existing field semantics. Breaking changes ship as a new major version.

OpenAPI snapshots for each release are published alongside the binary in the artifact registry. Pin your generated clients to the snapshot version of the service you target, not “latest”, to keep CI deterministic.

Internal and console APIs

First-party console, admin-console, service-local, and service-to-service APIs are not part of this public API reference. Internal interactive references use Scalar behind insider docs authentication. The public developer reference is a read-only Stoplight Elements page generated from the public OpenAPI documents.