Skip to content
TDACorpIDENTITY
Latest
Sign in

Versioning policy

What carries a version in identity today, what has no version yet, and what is and is not promised about change.

On this page

This page is about change: how you find out which version of something you are talking to, and what to expect when it changes. It states what exists today and nothing more. Identity is In development, and no deprecation schedule or compatibility guarantee has been published yet. Where a section says "not promised", read it literally.

What carries a version#

ThingHow it is versionedWhat you can rely on
Account APIA v1 path prefix: /v1/me.The prefix names the generation. Only v1 exists.
Token claim shapeThe ver claim in the ID token and the access token, currently 2.A change that breaks the shape of a token changes this value. A resource server that needs to tell the shape can gate on ver.
OIDC and OAuth endpointsThe discovery document, read from the standard well-known address.The set of endpoints, grants, algorithms, scopes and claims in discovery is what the provider supports at that moment. Read it instead of hard-coding.
Error codesThe generated Error codes page.A code is added to the list when the server begins to return it.
This documentationVersioned books. Today there is one, labelled Latest.The page you read describes the current behaviour.

The token shape#

ver is raised when the claim set changes in a way that is not compatible with the old one. Treat a token whose ver you do not recognise as one you cannot interpret, and refuse it rather than guessing. Do not depend on claims that are not on Token claims. In particular, the version counters av, pv, pvt and rv are for identity's own checks; their presence, absence and values can change.

How to code defensively#

These rules keep an integration working through additions.

  • Ignore what you do not know. A JSON answer can gain fields, a token can gain claims and discovery can gain members. Read the ones you need.
  • Read discovery. Take endpoint addresses, supported algorithms and acr_values_supported from it, and cache it for a short time.
  • Branch on the error code, not the text. The text of an error is meant for a person and can change. The error and code values are the stable part. An unknown code is a failure; treat it like server_error and do not loop.
  • Use Retry-After. Never hard-code a limit; see HTTP status codes and Retry-After.
  • Use the SDK for the protocol work. It handles the proof and nonce details for you; see Build with identity.
  • Verify the issuer's keys through JWKS. Signing keys are replaced on a schedule and an old key stays in the key set for an overlap period, so fetch the key set rather than copying a key.

What is not promised#

  • No date or notice period for removing a route, claim or error code.
  • No statement that the account API will stay the same shape within v1.
  • No promise that a status word on a page ("Planned", "In development") will become "Available" by any date.

When identity commits to a compatibility rule, it will be written here and the pages it changes will say so. Until then, the generated reference pages are tested against the server's own tables, so they are the most reliable statement of what the server does today.

Related#

Verified against commit 4fd66ff