Transition from API v2.0 to v2.1; required changes for developers

Relevant to: Event Lead Management

On 19th December 2020, changes will be made to the way authentication works on our public API.

These changes are required for all API clients; existing authentication and access tokens will stop working after this date, as they are no longer compatible with the new version of the API (v2.1) which will immediately replace all other versions. Our authorisation documentation will be updated to reflect the change, and you can find it inside the full v2.1 API documentation here.

Summary of changes

Prior to 19th December 2020, the authentication worked as follows:

• Make a request to /auth using your account developer API Key.
• This would return an access token which would be re-used with all subsequent API calls.

What is changing:

• The authorization endpoint has been replaced by a new endpoint.
• The payload sent to this new authorization endpoint has changed.
• The payload returned from the new authorization endpoint has also changed.
• The refresh_token has been deprecated.
• All endpoints that contain /v2/ will be deprecated and will return a 503 status code and the following message in the response body after 19th December 2020. Any endpoints in use will need to be modified to contain /v2.1/.
  
  The response and message at these endpoints will be as follows:

  { 
     "error": { 
         "message": "This version (V2.0) of the Integrate Events API is deprecated.
   Please update to the latest version of our API, and refer to the documentation 
  here https://api.integrate-events.com/docs"
     } 
  }

Step by step changes to be made

For direct use of the API (when not using our PHP SDK)

The changes you need to make to continue using the API with the new authentication are:

1. On or after 19th December 2020, you will need to log into your Events dashboard and using the option on this page will need to generate a new API Key.
   • You will not be able to generate a working API key until 19th December 2020, which is when the new v2.1 API will be activated. Keys generated before this date will not function after this date.
   • For information on re-generating your API key, see Using the Public API.
     
     
2. Using the new API Key, you will need to call the new authentication URL https://auth.integrate-events.com/ (which replaces the old authentication URL, https://api.integrate-events.com/v2/auth/ ).
   •  Note: there is a small chance this new URL may be altered before the date, so we advise you confirm by checking back here on the 19th December to ensure you have the right URL.
     
     
3. You will need to update the payload format sent to the authentication URL as shown in the API v2.1 documentation here.
   • Note: this payload contains a new audience key, and the value will need to be set to the string https://api.integrate-events.com/ as per the documentation (this value will remain static).
     
     
4. This will generate and return a payload, containing an access token - access_token.
   
   
5. The new access token - access_token - can be directly substituted into all places the old access token was used in your code.
   
   
6. Any references to the old refresh_token (previously supplied in the response body) should be removed from your code as it's no longer supplied by the API.
   
   
7. You will need to ensure you have updated all your endpoints to use the /v2.1/ url structure (rather than /v2/).

For exact details (including endpoints, payloads and responses) please refer to the formal authorisation guide in our API v2.1 documentation here.

If you are already using the PHP SDK

We are a releasing a new version of the (PHP) SDK compatible with API v2.1, and if you are using the SDK, most of the changes are handled for you. To update the SDK, you will need to run the following command on or after 9th December 2020, which is when we will release the updated package. This date is subject to change; any updates will be posted here as they happen.

composer update akkroo/akkroo-sdk-php

All you will need to do is remove any references you may have to the refresh_token from former versions of the API, as this is no longer supplied by the API (it is unlikely you will have referenced it, but just in case).

For more help, get in touch with our Support Team or your Customer Success Manager.