Skip to content

#195 · Public API: Strict UUID Validation on ID Path Parameters

Availability: General Availability

ID path parameters across the Escape Public API (v3) are now validated as UUIDs at the edge. Requests carrying a malformed identifier are rejected with a 400 Bad Request before they reach the platform, instead of surfacing as a 500 Internal Server Error after a failed internal lookup.

What's New

  • UUID validation on ID path parameters: {assetId}, {eventId}, {issueId}, {profileId}, {projectId}, {roleId}, {bindingId}, {scanId}, {userId}, and the integration {id} (including the ticket-lookup sub-endpoints) now require a UUID.
  • UUID validation on the audit log actor filter: GET /v3/audit/logs?actor=… requires a UUID.
  • Workflow filters validated per trigger: the workflow filter is now validated against the schema of the filter's trigger target, so the integrations filter enforces UUIDs on ids, projectIds, and locationIds, and a locationIds filter is honoured. A stored workflow filter holding a malformed id now matches nothing instead of erroring the automation that runs it.
  • Correct fault classification: malformed identifiers now answer 400 (customer fault) instead of 500 (platform fault), so they no longer count against the API availability SLA.

Why It Matters

Identifiers that were never valid (truncated IDs, comma-joined IDs, stray quotes) used to travel all the way to the internal GraphQL API and come back as an opaque 500. Those failures were indistinguishable from a platform outage in monitoring. They are now answered with a clear, immediate 400 Bad Request.

Compatibility

Hard-breaking changes

None.

Soft-breaking changes

The OpenAPI spec now declares format: uuid on the affected path parameters, on the audit log actor query parameter, and on the id lists of the integrations workflow filter. Calls that used to return 500 for a malformed identifier now return 400. Regenerated SDKs type these parameters as UUID strings; every previously successful request behaves exactly as before.

One behaviour change to be aware of: a locationIds filter on an integrations workflow was silently dropped before this release (it never filtered anything). From this release on it is applied — workflows created or updated with a locationIds filter will filter on those locations.