Guidelines to migrate to our new API version

Our platform is constantly evolving, and as part of our recent auth & dashboards release we’ve also upgraded our API version to version 3. Thankfully while the version number change is major, and there is a breaking change, generally there’s not much to adjust.

0. New way to get an API Key

Before, the only way to access Contenda was via an API Key - didn’t matter whether you accessed our web app or our API directly.

Now, all our users can sign up in the web app where you can find the option to generate an API key from the dashboard. These new (version 3) API keys are 43 characters long, so they’re easily distinguishable from the old (version 2) API keys, which are 72 characters long.

1. API URL Update

In version 2 of our API, you were used to interacting with the API URL prefix api/v2/ and the https://prod.contenda.io domain. With version 3, we have updated this to be /api/v3/ and https://prod.contenda.co (notice the TLD change). This new prefix will direct your requests to the appropriate API version, with a few more capabilities and most importantly, using the new authentication methods.

We’ll still be supporting “version 2” until the end of this month. But it’s important to note that the TLD change is required for both versions. You’ll need to use https://prod.contenda.co as https://prod.contenda.io will not work anymore.

Our documentation for all our endpoints is available here: https://prod.contenda.co

2. Changes in Authentication

The way you authenticate to our API has also changed. In the previous version, you had to use the /api/v2/identity/token endpoint to obtain an access token.

To obtain your access token for version 3 of the API, use the /auth/v1/flow/apilogin endpoint. This authentication endpoint requires you to submit user_email and api_key within the JSON body of your request:

{
  "user_email": "your_email@example.com",
  "api_key": "bla4815162342bla"
}

To see the exact call and expected response, you can check our auth docs.

3. Token Supply Method

When interacting with our old API you had to supply your access token as a query parameter token. We have updated this in version 3 for enhanced security and ease of use - matching industry standard practices.

To call the version 3 APIs, you need to supply your token in the Authorization header as a Bearer value.

4. Setting the User-Agent Header

While this was not a requirement in the previous version (and it’s still not in version 3), it’s recommended that you set the User-Agent header in your requests. Including this information in your requests can help us provide you with better, more personalized support.

In conclusion

We understand that any transition can bring challenges, but we believe these changes will ultimately offer a more efficient, secure, and user-friendly experience for everyone using our platform. We appreciate your understanding and cooperation during this transition period, and our support team is always ready to help with any issues or concerns you might have.

Our current plans are to deprecate the old “version 2” of the API on July 31st, 2023.

Thank you for your continued support and use of our platform! 🚀 We’re looking forward to seeing what amazing things you will build with our new and improved API!