When building Auth0 products, we resolve to:
  • Deliver value to customers early and often, iterating based on their feedback
  • Seek a deep understanding of our customers and consider them in every decision
  • Relentlessly acquire and analyze data, so we can make better choices
  • Visualize and design for current, idealized, and future versions of our whole product when adding features
This document provides guidance on what constitutes backward-compatible (non-breaking) and backward-incompatible (breaking) changes in the Auth0 platform. The distinction between these changes helps developers anticipate potential impacts on their applications when consuming Auth0 services. This document outlines common changes and their compatibility to help set expectations for integrations. The changes described are not exhaustive or comprehensive; for more details on breaking changes, read the topics below.
Read…To learn…                                
Product Release StagesHow Auth0 stages, releases, and retires product functionality.
Migration ProcessHow Auth0’s deprecation and migration process works.
Deprecations and MigrationsAbout current deprecations and how to migrate to new behaviors or features.
Past MigrationsPast migrations previously enabled for customers.

​
Auth0 APIs

Auth0 exposes and maintains APIs like the Authentication and Management APIs, each of which define a contract between Auth0 and its customers based on the documented API specifications and its associated artifacts. Auth0 follows recognized standards from bodies such as IETF and OIDC; where standards do not exist, proprietary APIs are developed while adhering to best practices. Changes to these APIs, whether backward-compatible or backward-incompatible, are necessary from time to time to improve their functionality, security, or performance.

​
Backward-compatible, non-breaking changes

A backward-compatible change does not disrupt the interoperation between the Auth0 platform and customer applications and does not require customers to take immediate action or participate in the migration process. Examples of non-breaking changes include:
  • Opaque Strings: The format and size of opaque strings (e.g., tokens, IDs) may change. Clients shouldn’t assume a fixed size or format. The maximum size for opaque strings will not exceed 4096 characters.
  • Size: Per the specification (RFC6749), the size of JWT credentials is undefined. Auth0 may issue variable-sized JWTs, and clients should not assume a specific size.
  • Authorization Code Size: Clients should expect that authorization codes, as per the OAuth specification, may vary in size.
  • Unrecognized Response Parameters: Clients must ignore unrecognized response parameters, allowing Auth0 to add new features without affecting current functionality.
  • New Resources, Fields, Headers, or Scopes: The addition of new API resources, fields, headers, or scopes will not impact existing clients that do not recognize or use these elements.
For a more detailed explanation of backward-compatible changes, refer to Auth0’s API change guidelines in the product lifecycle stages.

​
Backward-incompatible, breaking changes

A backward-incompatible change can cause failures when it alters the interoperation between the Auth0 platform and customer applications. When such a change is necessary, it follows the deprecation and migration process to provide notice and support for customers to adjust their tenant implementations. Examples of breaking changes include:
  • API Resource Removal: If an API resource is removed or renamed, clients relying on that resource will experience a breaking change.
  • URI Structure Changes: Modifying the structure of an existing URI may disrupt clients that depend on it.
  • Method, Parameter, or Field Removal: If a method, parameter, or field is removed or renamed, this will result in a breaking change for clients using these elements.
  • Default Value Changes: Changes to the default value of a field may impact existing integrations and constitute a breaking change.
  • Error Response and Status Code Changes: Modifications to error response formats, error codes, or status codes can break existing client behavior.
  • JWT Format: Changes to the JWT format of tokens are breaking changes
  • JSON Format: Changing the type of a JSON value is a breaking change.
Any breaking change triggers the deprecation process, in which customers are notified and provided at least six months to migrate to the new behavior. For more details, refer to the deprecation and end-of-life process.

​
Auth0’s commitment

Auth0 minimizes disruptions caused by backward-incompatible changes using the following process:
  • Deprecation Announcement: Auth0 announces the deprecation to provide customers notice of an upcoming change.
  • Migration Window: Customers are given a minimum six-month window to migrate to the updated functionality, with guidance provided in our migration process.
  • End of Life: When the migration window closes, the deprecated feature is moved to the end-of-life stage and is no longer available.

​
Undocumented APIs

Undocumented Auth0 APIs are considered private and subject to change without notice. These APIs are not covered by the deprecation process and customers should avoid relying on them for production systems.