Your app cannot access ePages data without getting authorisation from the merchant first. In this section we will help you through this authorisation process.
PRO TIP: This process describes a perfect scenario. Make sure you gracefully handle failures, call limits, communication errors etc.
You retrieved a Client ID and a Client Secret that are known to both ePages and your application. Visit the get your credentials page for further information on this subject. Your app uses these credentials for identification during the authorisation process.
Before jumping into the authorisation process, let’s look at some terms that will be used in this section.
|Merchant||A shop owner giving permission to an App to access his shop’s data through the REST API. Within the OAuth 2.0 protocol this is referred to as resource owner.|
|ePages||This is where the App can view and modify a shop’s data by accessing the REST API. Within the OAuth 2.0 protocol this is referred to as service provider.|
|App||An application that would like to access a shop’s data. The Merchant must grant permission before the App can access any data. Within the OAuth 2.0 protocol this is referred to as client.|
1. Ask for permission
The merchant decided to install your app. Great! They will then be asked, whether they want to grant your app the permissions that it is requesting. While submitting the app, you have to define a scope, which outlines the permissions and access needed by your app. ePages displays the user consent form to the merchant as follows:
2. Confirm the installation
The merchant agrees and submits the consent form by clicking the button Install on the consent page. The merchant will be redirected to the app’s Application Callback URL.
3. Receive authorisation code
ePages makes a
GET request to the Application Callback URL provided by the app developer.
The required query parameters, see table below, will be automatically passed by ePages.
SSL required! All API access is over HTTPS.
Substitutions would be made as given in this example table:
||Authorisation code that is required for the app installation process to obtain the
||The base API URL, that uniquely identifies the merchant. The
||The URL which the merchant should be redirected to after the app installation.||https://creamyiceshop.com/epages/CreamyIceShop.admin/?ObjectID=17811&ViewAction=MBO-ViewAppDetails&appID=54f46f318732110bd85f41c7|
||The URL to obtain the
||The signature is a message authentification code. It is calculated with the
Your app can use the
code in combination with your Client ID and Client Secret for obtaining an
This code is temporary and will be obsolete after app installation.
Although it is optional to validate the
signature query parameter, we highly recommend to do so, in order to verify that your request was not changed, and for sure has been provided by ePages and no external, insecure party.
In order to understand how to verify the
signature, see the following Java code example:
4. Registration (optional)
If your app requires a registration process, this optional step can be included before obtaining the
During this, the app would display the registration or login form to the merchant.
5. Exchange authorisation code for access token
To get an
access_token, make a
POST request to the token endpoint provided by the
access_token query parameter on the Application Callback URL with the following parameters:
||The code provided in the Application Callback URL (see above).|
||The client key for the app (see the get your credentials section).|
||The shared client secret for the app (see the get your credentials section).|
Mind the Content-Type! The
POST request has to be x-www-form-urlencoded!
In a successful response, a JSON object is returned with an
access_token that can be sent to the ePages API, similar to the following:
This is a permanent
access_token that can be used to access the shop’s data as long as the app is installed in the merchant’s shop. This
access_token allows your application to act on behalf of the merchant on this specific shop.
Top secret! With this
access_token you make authenticated requests to the shop’s data. Store the
access_token securely against the
Do not share the
access_token with anyone!
The following table is an example on how to manage the data of different merchants.
Note: Unlike the
api_url, the derived Shop does not uniquely identify a merchant.
6. Redirect the merchant
Once the authorisation process is complete, your app has to send the merchant back to the
return_url the app received before.
In case of a successful app installation, the merchant will be able to open the app in the App Store. If an error occurred during installation, the Install button instead of the Open app button will be shown.
The app will also appear in the administration area in the section My apps.
Make an authenticated request to the API
Now that your application has received an
access_token, it can make authenticated requests to the ePages API.
Fancy more information?
All API calls are authenticated according to the OAuth 2.0 protocol. Read here for further details: OAuth 2.0 protocol.