Versioning

The current API major version is v1, embedded in the path: /v1/enroll, /v1/verify, /v1/delete. Breaking changes ship as v2 alongside v1; you have at least 12 months to migrate. Non-breaking additions ship under v1 directly.

What's a breaking change

• Removing or renaming a JWT claim
• Changing the signature algorithm
• Changing required parameters or removing a field
• Changing an error code
• Changing the score range or threshold semantics

What's not a breaking change

• Adding new optional parameters
• Adding new claims to the JWT
• Adding new endpoints
• Tightening anti-spoof scorers (your false-accept rate drops; false-reject rate may rise marginally — telemetry alerts on regressions)

Why no webhooks

The signed JWT is the contract. Your backend gets the verdict synchronously in the /verify response. There is nothing asynchronous about a verification — it either succeeds in 292ms median or fails fast on a gate. A webhook would either (a) duplicate the synchronous result, or (b) introduce eventual-consistency where the whole point is no eventual-consistency. We're not building that.

Deprecation policy

When v2 ships, we publish a deprecation date for v1 that is at least 12 months out. During overlap, both versions accept traffic. The dashboard shows your tenant's per-version traffic split so you can track migration progress.