Update to a Newer Version of FusionAuth

This section describes how to update any instance of FusionAuth to the latest version.

Stay Informed#

To find out about new releases, try one of the following options:

• Bookmark the release notes and subscribe to the release notes RSS feed

• Sign up for release notifications:

  Submit

  Form submission blocked by your browser. Please temporarily disable your ad blocker or privacy protection to submit.

  Thank you! Your submission has been received.

FusionAuth Versioning#

FusionAuth releases come in three flavors: major, minor, and patch.

You can tell what a release is from the rightmost non-zero number in the version: <major>.<minor>.<patch>. For example:

• 1.0.0: major release, may significantly change the API
• 1.63.0: minor release, may make small changes to the API
• 1.45.1: patch release, never changes the API

The FusionAuth team provides detailed information about every change in every version, including tying the change back to a GitHub issue. To understand how a version update affects your systems, read the release notes.

Client Library Versioning#

FusionAuth represents releases with a version number: <major>.<minor>.<patch>. Major releases can add, change, or remove functionality from the API, minor releases can add to the API, but patch releases never change the API. Client library version numbers show you which API version a client library was built for.

We recommend using a client library with the same major and minor numbers as your FusionAuth instance version. This ensures that your client library supports the same APIs as your FusionAuth instance.

If you don't keep your client library in sync with your FusionAuth version:

• you won't be able to access new API endpoints
• you won't benefit from client library improvements (e.g. exponential backoff, improved HTTP connections, etc)
• you could experience subtle bugs when existing API endpoints change behavior (e.g. changed argument order in an untyped language)

Patch releases don't always exist for client libraries since many bugfixes and small changes don't impact client libraries. FusionAuth only creates patch releases for client libraries when we fix an issue in the library, so always update to the latest patch release for your major and minor version. Patch releases may also update dependencies, language engines, and operating systems, as we follow the deprecation and sunsetting policies of each platform.

Consider a user whose FusionAuth instance runs version 1.61.1. They should:

• use Java client library version 1.61.2, the latest patch release for 1.61.x
• use TypeScript client library version 1.61.0, the latest patch release for 1.61.x

This theoretical user also ought to update their FusionAuth instance to 1.61.2, the latest patch for the major and minor instance version.

Update a FusionAuth Cloud Deployment#

To update your FusionAuth Cloud deployment, see the Update a Deployment Guide.

Update a Client Library#

Older FusionAuth client libraries should work properly with newer FusionAuth versions upon updating. However, once you use new features on that instance, FusionAuth might return enumeration values that older clients do not understand. This can cause client operations to fail.

Note that newer FusionAuth client libraries might not be compatible with older FusionAuth versions.

The release notes provide more information about API changes between versions.

If you are using an OIDC-compatible library in your application to log your users in, it is unlikely that this integration would require modification, but test it in a non-production environment to make sure.

Update FAQs#