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 spec

Each DotID service may publish 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.

The public gateway exposes external OpenAPI specs at one URL per capability:

  • Identity — dev: {{ dotid_api_dev }}/identity/openapi.json; prod: {{ dotid_api_prod_pattern }}/identity/openapi.json

  • Audit — dev: {{ dotid_api_dev }}/audit/openapi.json; prod: {{ dotid_api_prod_pattern }}/audit/openapi.json

  • PassPort — dev: {{ dotid_api_dev }}/passport/openapi.json; prod: {{ dotid_api_prod_pattern }}/passport/openapi.json

  • Service Catalog — dev: {{ dotid_api_dev }}/service-catalog/openapi.json; prod: {{ dotid_api_prod_pattern }}/service-catalog/openapi.json

Fetch from the command line:

curl -H "Authorization: Bearer $TOKEN" \
  {{ dotid_api_dev }}/identity/openapi.json > identity.openapi.json

The live public spec is generated from the running gateway/export contract. If a field appears in the live spec but not in older client SDKs, regenerate your client.

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}/users... — identity users.

  • /identity/v1/accounts/{accountId}/groups... — groups.

  • /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 users.

  • /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. Public developer references use read-only Stoplight Elements pages generated from public OpenAPI documents.