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 when you create your tenant. 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. You can visit your Dashboard to upgrade your API version. As a precaution, use API versioning to test a new API version before committing to an 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.
  • Adding new Hook types, MFA types & Social providers.
  • 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.

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 tenant’s default API version. To test a newer version for API calls, set one of X-PlusAuth-Version or Accept-Version headers.

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 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.