Versioning & deprecation
Verification is consumed through the @valyd/sdk package — you pin the SDK version, and the
SDK tracks the current verification contract for you.
What is NOT a breaking change (may ship any time)
These are additive and safe — your integration must tolerate them:
- Adding a new SDK method, a new optional parameter, or a new workflow feature/check.
- Adding a new field to a response object (e.g. a new key inside
check.data). - Adding a new enum value (a new
check.status, a new failuresignal, a new eventtype). - Making a previously-required field optional.
- Bug fixes and performance changes that don’t alter the documented contract.
Build defensively: ignore unknown response fields, and don’t hard-fail on an unrecognized enum value — treat unknown verification states as not approved until your application explicitly supports them.
What IS a breaking change (gets a new major SDK version)
- Removing or renaming an SDK method, parameter, or response field.
- Changing a field’s type or the shape of a response.
- Making an optional parameter required, or tightening validation.
- Removing an enum value, or changing the meaning of an existing one.
- Changing authentication or error semantics.
Breaking changes are never made to a released SDK major in place. They ship under a new major version; the pin you already have keeps working.
API versions
The API’s major version (currently v2) is part of every endpoint path. Every response also carries it in a header:
Valyd-Api-Version: v2A breaking change ships as a new major (v3) alongside the current one. The SDK major and the API major move together, so pinning the SDK pins the API.
The OpenID Connect endpoints (/api/auth/oidc/*, discovery) are not versioned. They follow the
OIDC and OAuth standards, and their URLs come from
discovery. Changes to them are announced on the
Deprecations page.
Deprecation policy
When a method or field is deprecated:
- It is announced in the Changelog and marked deprecated in this documentation.
- It keeps working for a minimum 6-month migration window after the announcement.
- The SDK surfaces a deprecation notice pointing at the replacement.
You never have to migrate on our schedule inside a major version — pin the SDK (see below) and you are stable until we announce that major’s deprecation with the window above.
How a deprecated endpoint tells you
From the day an endpoint (or a whole major) is deprecated, every response from it carries standard headers, so you can detect it in code, not only in the changelog:
| Header | Example | Meaning |
|---|---|---|
Deprecation | @1793491200 | Deprecated since this time (Unix seconds, RFC 9745 ) |
Sunset | Sat, 01 May 2027 00:00:00 GMT | It stops working on this date (RFC 8594 ) |
Link | <https://docs.valyd.work/docs/deprecations>; rel="deprecation" | Where the migration is explained |
The endpoint keeps working until the Sunset date. The
OpenAPI spec also marks it deprecated with its date.
After the Sunset date it answers 410 Gone with a pointer to the replacement, never a silent
404:
{
"success": false,
"data": [],
"error": {
"code": "endpoint_removed",
"message": "This endpoint was removed on 2027-05-01. Use the replacement endpoint instead. See https://docs.valyd.work/docs/deprecations"
}
}Watch for the headers. The SDK surfaces them as a deprecation notice. If you also see raw responses (a proxy, logging, or your own HTTP wrapper), a one-line check gives you months of warning:
const res = await fetch(url, options)
if (res.headers.get('Sunset')) {
console.warn(`Valyd: ${url} is deprecated and stops working on ${res.headers.get('Sunset')}`,
res.headers.get('Link'))
}Recommended practices
- Pin the SDK with a caret range —
npm i @valyd/sdk— so you get compatible patch and minor updates without an unexpected major bump. - Subscribe to the Changelog for additive changes and any deprecation notices.
- Log or alert on the
Sunsetresponse header (see above), so a deprecation reaches you even if nobody reads the changelog. - Handle unknown enum values and extra fields gracefully (see “build defensively” above).