OpenAPI reference

DotID exposes its REST APIs as OpenAPI 3.1 specifications served live by each service. This page is your jumping-off point for the live spec and for the request/response schemas that govern every IAM call.

Live spec

Each DotID service publishes its OpenAPI document at the standard springdoc path /v3/api-docs (JSON) or /swagger-ui.html (interactive UI). The public gateway exposes the live OpenAPI specs at one URL per service:

  • IAM — https://[dev-]api.flexgalaxy.{com,ai}/iam/openapi.json

  • Audit — https://[dev-]api.flexgalaxy.{com,ai}/audit/openapi.json

Fetch from the command line:

curl -H "Authorization: Bearer $TOKEN" \
  https://dev-api.flexgalaxy.com/iam/openapi.json > iam.openapi.json

The live spec is generated from the running service’s annotated controllers, so it is always in sync with the deployed binary. If a field appears in the live spec but not in older client SDKs, regenerate your client.

Authorization service spec

The DotID Authorization service is reached through the tenant gateway. Public routes use gateway prefixes only; internal /api/v1/... controller paths are an implementation detail.

  • /iam/v1/accounts/{accountId}/users... — IAM users.

  • /iam/v1/accounts/{accountId}/groups... — IAM groups.

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

  • /iam/v1/accounts/{accountId}/access-keys... — access keys.

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

  • /iam/v1/identity-center... and /iam/v1/account-assignments... — permission sets and Identity Center account assignments.

  • /authz/api/v1/authorize — the PDP entry point (see API authentication and JWT validation for the request/response shape).

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

Audit service spec

The DotID Audit service is exposed through the gateway’s /audit/ prefix:

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

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

  • /audit/v1/events — platform-level audit event collection.

  • /audit/v1/events/{event-id} — 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.