API compatibility and deprecation#

This page states what ProudAuth promises to API clients, SDK users and event consumers when it changes, and how it announces changes that need client work (API-013).

Versioned surfaces#

There is one supported management API version, v1. A future v2 would be served next to v1 for at least the deprecation window below.

Changes that do not need client work#

Within v1 and within an event's event_version, releases may:

• add endpoints, optional request members, response members and response headers;
• add event types and optional members of an event's data;
• add values to fields documented as open sets (problem code, audit event types, security signal names, next_actions types);
• tighten validation of input that was already documented as invalid;
• change the order of members and of unordered list items.

Clients must ignore response members and event members they do not know, must not depend on member order, and must treat unknown enum values of open sets as "other".

Changes that need client work#

Removing or renaming an endpoint, member or event; making an optional request member required; changing a member's type or meaning; or changing an error a client is expected to handle is a breaking change. ProudAuth makes one only:

1. with a new version (/api/v2/, a new event_version) served alongside the old one, or
2. after a deprecation period, except for security fixes (below).

Deprecation process#

• The change is announced in the CHANGELOG under Deprecated, naming the replacement and the earliest removal release.
• The operation is marked deprecated: true in the OpenAPI document and its description names the replacement. No operation is deprecated today; the server does not send Deprecation or Sunset headers yet.
• The minimum window between the first release that announces a deprecation and the release that removes it is two minor releases and at least six months.
• Removal is listed in the CHANGELOG under Removed with the upgrade steps clients need.

Security exceptions#

A change that removes insecure behavior may skip the window. When the risk allows, it ships first behind a realm or operator setting with the secure behavior as an opt-in, announced in the CHANGELOG under Security fixes with the client upgrade needed; when the behavior is being exploited or cannot be made safe, it changes in the next release. Examples in the current development history: PATCH /organizations/{org} now requires If-Match when it changes policy (API-010), and webhook destinations are checked against the egress policy at registration.

Protocol options#

Newer OAuth and OpenID Connect capabilities are opt-in, per client or per realm, so existing clients keep their behavior:

Discovery changed compatibly: response_modes_supported now lists query.jwt and jwt, userinfo_signing_alg_values_supported lists the realm's algorithms after "none", grant_types_supported lists jwt-bearer, frontchannel_logout_supported and frontchannel_logout_session_supported are true, and encryption, authorization-signing and mutual-TLS members were added (oauth-oidc-profile.md). Clients must ignore members and values they do not use.

Coordinate a change of the realm's signing algorithm (keys.signing_algorithm) with clients that registered userinfo_signed_response_alg or authorization_signed_response_alg (responses are always signed with the active key, and such a client cannot be updated until its value matches) and with fapi2 clients, which need PS256, ES256 or EdDSA (response-security.md).

Validation that was tightened as a security fix, without a deprecation window: every aud value of a private_key_jwt client assertion must name this server (an assertion also addressed to another party is refused), and post_logout_redirect_uri is checked before the session ends.

Events#

An event type's payload changes compatibly within its event_version. Every event type exists in versions 1 and 2, which differ only in the envelope (version 2 names the organization organization_id and states the payload_form); each webhook subscription chooses the version it receives, and version 1 stays the default. A breaking change introduces a new event_version and keeps delivering the old one to the subscriptions that chose it for at least 12 months after the new version is published (the support window of the extension contracts, longer than the API deprecation window below; extension-contracts.md). Consumers deduplicate by event_id and must not rely on delivery order.

Pre-action hooks, plugin manifests and lifecycle workflow definitions are versioned the same way, each independently of the others and of server releases: a hook pins its contract_version, a plugin its manifest_version, a workflow definition its schema_version.

SDKs#

The Go, Node.js, Dart and PHP SDKs follow the API: they gain methods for new endpoints in minor releases, keep deprecated methods working for the deprecation window and mark them deprecated in their documentation. Their administration clients report the Deprecation and Sunset headers of deprecated operations to a callback (OnDeprecated in Go, onDeprecated in the others). Runtime support, SDK versioning, breaking changes and the security-update policy are in sdk-compatibility.md.

Database and configuration#

Database migrations are expand-only unless marked -- proudauth:compat=contract; contract migrations need the operator's backup reference and are announced in the CHANGELOG with the release that may run them. Deployment configuration keys are never silently ignored: an unknown key or a malformed environment override stops the process, and identity-cli config-diff shows the effect of a configuration change before rollout.

Declared protocol profiles#

Some optional protocol extensions are offered as declared profiles: a named specification version, opt-in per realm, with what is and is not implemented listed. They are internal-test claims only; no conformance suite has been run (interoperability.md).

A newer version of one of these specifications would be added as a new declared profile next to the old one, under the rules above.

Capabilities not offered#

The specification lists these capabilities as optional (the P3 extensions, JAR and a gRPC management interface). They are not offered, and nothing in the product presents something else as them (APP-020). Each entry says why and what an implementation would have to provide before it could be offered.