API integration process changes - January 2022

Only relevant if you have already worked with our API before January 2022

As part of ongoing security improvements, there is a new process for initially connecting your third-party app with existing ready2order accounts.

Who is affected by this?

  1. If you are currently developing a 3rd party app integration, the authentication process has changed.
  2. If you have an existing integration that revokes access regularly, the integration needs to be updated to the new process.

What is this document?

This document will guide you through the necessary changes which need to be done in third party apps to make sure the initial authentication process for ready2order accounts will continue to work.

To work with ready2order's API it's necessary to request an API token for a specific ready2order account. To obtain this API token it's necessary to redirect the ready2order merchant to a specific page, where the ready2order merchant needs to login in. After a successful login the ready2order merchant needs to approve that your third party app will be able to access accounts data.

What part is affected by this change?

The process by which you get the initial API developer token has changed.

If you have any reason to revoke the API developer token, the process by which you will get a new one is changed as described below.

What will change?

Old process

A third party developer used to redirect the ready2order merchant to this page.

This process is deprecated and decommissioned by 28th of February 2022.

New process

  1. Use your developer token (which was sent to you via email when registering as an API developer) to request a temporary grant-access-token
If you have lost the original email and don’t have the token stored in the configuration of your third party app, please contact ready2order support.

POST https://api.ready2order.com/v1/developerToken/grantAccessToken

Authorization: {YOUR_DEVELOPER_TOKEN}

Accept: application/json

{

  "authorizationCallbackUri" : null|string

}

Optionally a body param authorizationCallbackUri can be provided which must have a valid, publicly reachable URL which we will redirect the ready2order merchant after approval or decline. In case it is provided we will redirect the ready2order merchant to this page with the following parameters.

GET https://example.com/redirect-endpoint?status=approved|declined&accountToken=${ACCOUNT_TOKEN}&grantAccessToken=${GRANT_ACCESS_TOKEN}

Please note that it's considered best practice to compare thegrantAccessTokenpassed to theauthorizationCallbackUriwith the grant-access-token on your side to avoid unexpected outcomes.

  1. Use thegrantAccessUriof the response and redirect the ready2order merchant to this page.

Next, the ready2order merchant will be prompted to login and can either grant access to your app or decline it.

If the ready2order merchant approved and no authorizationCallbackUri was provided, the account token for using the API will be just displayed to the ready2order merchant.

If the ready2order merchant approved and a authorizationCallbackUri was provided, the ready2order merchant will be redirected to the given and the account token for using the API can be read from query param accountToken.

 For more information, check out the API Documentation
If for any reason the account token is invalidated, the process needs to be repeated to get an active account token.


How did we do?