This article clarifies whether the Okta Application Programming Interface (API) is subject to change and provides guidelines for maintaining application compatibility.
- API lifecycle management
- Developer documentation
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 in Paths: The API version is included in the URL path. For example, the Users API currently uses version v1:
https://<yourOktaDomain>/api/v1/users. -
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.
