Skip to Content
VerifyVersioning & deprecation

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 failure signal, a new event type).
  • 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: v2

A 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:

  1. It is announced in the Changelog and marked deprecated in this documentation.
  2. It keeps working for a minimum 6-month migration window after the announcement.
  3. 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:

HeaderExampleMeaning
Deprecation@1793491200Deprecated since this time (Unix seconds, RFC 9745 )
SunsetSat, 01 May 2027 00:00:00 GMTIt 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')) }
  • 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 Sunset response 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).
Last updated on