# 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](/docs/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`). 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--`, 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: @`: the deprecation date as an RFC 9745 structured date; - `Sunset: `: the removal date (RFC 8594); - `Link: ; rel="deprecation"` and `Link: ; 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: / (/)` 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.