Your API version controls the API behavior you see (e.g., what properties you see in responses, what parameters you’re permitted to send in requests, etc.). Your version gets set the first time you make an API request. When we change the API in a backwards-incompatible way, we release a new dated version, but to avoid breaking your code, we don’t change your version until you’re ready to upgrade.

Backwards-compatible changes

PlusAuth considers the following changes to be backwards-compatible:

  • Adding new API resources.
  • Adding new optional request parameters to existing API methods.
  • Adding new properties to existing API responses.
  • Changing the order of properties in existing API responses.
  • Changing the length or format of object IDs or other opaque strings.
    This includes adding or removing fixed prefixes.
    You can safely assume object IDs we generate will never exceed 255 characters, but you should be able to handle IDs of up to that length. If for example you’re using MySQL, you should store IDs in a VARCHAR(255) COLLATE utf8_bin column (the COLLATE configuration ensures case-sensitivity in lookups).
  • Adding new hook types, MFA types & providers.

Upgrading your API version

If you’re running an older version of the API, upgrade to the latest version to take advantage of new functionality or to streamline responses, so the API is faster for you. Upgrading your API version will affect:

  • The API calls you make without a X-PlusAuth-Version header: the parameters you can send, and the structure of objects returned.
  • The structure of objects received from REST API and PlusAuth libraries.
  • The structure of objects sent to your REST API endpoints.
  • The structure of objects in hooks and customizable views or email/sms templates.

See the API changelog for details about how your default API version will impact these operations.

To see what version you’re running and upgrade to the latest one, visit your Dashboard.

When performing an API upgrade, make sure that you specify the API version that you’re integrating against in your code instead of relying on your account’s default API version. To test a newer version for API calls, set the X-PlusAuth-Version header.

Rolling back your API version

For 72 hours after you’ve upgraded your API version, you can safely roll back to the version you were upgrading from in your Dashboard.

API changelog

The changelog is a list of backwards-incompatible updates in the API. As described above, new additions and forward-compatible changes don’t need a new API version and will not appear in this list.