API versioning and deprecation policy

This page explains how KeenAuth versions its APIs, how a removal is announced and how long the SDKs, the CLI, the Terraform/OpenTofu provider and the MCP server receive security fixes. Every announcement is published in the changelog.

API versions

The management API carries its major version in the path (/v1). Within v1 only additive changes are made:

• a new endpoint;
• a new optional request field;
• a new response field;
• a new enum value;
• a new error code;
• a new event type.

Write your integration so that it accepts these additions.

A breaking change is made only in a new major version (/v2). Breaking changes are: removing or renaming a field, changing a type, adding a required field, changing default behaviour, and changing pagination, sorting or the default limit. v1 stays available for at least 24 months after v2 becomes generally available.

KeenAuth does not use date-based version headers; the major version in the path and the additive-only rule are the whole contract.

Beta and GA operations

Every operation is marked x-idp-stability: beta or x-idp-stability: ga in the OpenAPI document. A beta operation can change during a private or public beta and is not covered by the deprecation rules below; its responses carry the Idp-Stability: beta header. A ga operation is frozen: it changes only under the rules on this page.

Events and token claims

• Customer event types carry a schema version (v<n>). A breaking change to a payload creates a new schema version; both versions are delivered in parallel for 365 days and each webhook endpoint chooses the version it receives.
• Adding a token claim is additive. Removing a claim or changing its meaning is announced 365 days in advance, and claims_supported in the discovery document is updated.

Deprecation and removal

Removing an endpoint, parameter, claim, scope, event type, signature algorithm or other surface is announced in the changelog at least 365 days before the removal date. Every deprecation has an identifier of the form dep-<YYYY>-<NN>, a deprecation date, a removal (sunset) date, a replacement where one exists and a migration guide.

Security exception: to close a security vulnerability, behaviour within v1 can change without the 365-day notice. Such a change is published in the changelog with the security tag, and the affected environments are notified by email.

Signals in API responses

A response from an operation that is being removed carries:

• Deprecation: @<unix_epoch>: the deprecation date as an RFC 9745 structured date;
• Sunset: <IMF-fixdate>: the removal date (RFC 8594);
• Link: <doc_url>; rel="deprecation" and Link: <doc_url>; rel="sunset": the migration guide.

After the removal date the operation answers 410 with the problem code endpoint_sunset. OAuth and OpenID Connect protocol removals (a signature algorithm, a client authentication method, a parameter) cannot carry headers; they are counted per client and go through the same notifications.

Where you see your usage

• Environment log: a deprecation_notice record, at most once per hour, with deprecation_id, client_id and sunset_at.
• Dashboard: the Deprecations page shows the last 30 days by deprecation, client and SDK version; a banner appears from 90 days before the removal date.
• API: GET /v1/reports/deprecation-usage?from=&to= (permission reports:read).
• Email: to the account's owner and admin roles and the environment's technical contact, on the announcement day (every environment that uses the surface) and 180, 90, 30 and 7 days before the removal date (environments that used it in the last 30 days).

The official SDKs, the CLI, the provider and the MCP server send Idp-Client: <package>/<version> (<runtime>/<version>) with every request. The header is not authentication; it is used only for counting, and a malformed value is ignored. Usage counts store no IP address, User-Agent or end-user identifier.

SDK and tool support policy

The SDKs, the CLI, the Terraform/OpenTofu provider and the MCP server follow semantic versioning. A major version increases only with a breaking change in the language itself or with a new major version of the API.

• The product line as a whole receives security support for at least 5 years, counted from its general availability.
• Security fixes are released in the latest major version of each package, and upgrading to it is free.
• The previous major version receives security and critical bug fixes for 12 months after the new major version becomes generally available; then it reaches end of life.
• Every published security update stays available for at least 10 years, or for the rest of the support period if that is longer.
• From 90 days before end of life, an SDK writes a warning to your application's log with the server's Deprecation header and its own end-of-life date.
• End-of-life SDK versions are not blocked by the server; the dashboard and email warn you.
• End of support is announced in the changelog and in the package registry (npm deprecate; on PyPI a description, the release is not yanked).

Runtime support

The SDKs support the runtime versions that their vendors still support with security fixes: Node.js LTS, Python according to the upstream support schedule, the last two Go releases, Java 17 and 21, .NET LTS, PHP 8.2 and later, Ruby 3.2 and later, iOS 16 and later, Android API 26 and later. The minimum runtime matrix is published with every major version. A runtime that loses its vendor's support is dropped in a minor version, announced in the changelog 90 days in advance.