Okta API Stability and Versioning Policy
Last Updated:
Overview
This article clarifies whether the Okta Application Programming Interface (API) is subject to change and provides guidelines for maintaining application compatibility.
Applies To
- API Lifecycle Management
- Developer Documentation
Solution
The Okta API is versioned to ensure stability. Follow these guidelines to ensure the application remains operational:
-
Major Versioning: Breaking changes, such as removing or renaming a property, occur only in new API versions. Okta provides a migration path for new API versions and communicates end-of-life timelines when deprecating an API.
-
Versioning: The API version is included in URL Path or Header or API body.
-
Non-Breaking Updates: Okta reserves the right to add new parameters, properties, or objects to the API without advance notice. These updates are considered non-breaking. Design code to ignore unknown fields to prevent service disruptions.
-
Lifecycle Stages:
-
Early Access (EA) and General Availability (GA): These features are backward compatible and supported by Okta Customer Support.
-
Beta: These features are for testing in Preview orgs, are not supported by Support, and can change at any time.
-
-
Documented vs. Private Endpoints: Only use endpoints documented in the Reference overview. All undocumented endpoints are considered private, are subject to change without notice, and are not covered by any agreements.
NOTE: Identity Governance Access Requests for resource catalogs APIs use version v2.
