Make your first API call with complete parameters detail

Less than 5 minutes to read

Ensure the X3 user that will be used for your pairing request has the correct security profile.

Go to Administration > Users > Security profiles, and on the ‘thirdParties’ line ensure that ‘Create’, ‘Read’ and ‘Write’ are checked.

Execute the pairing request, for example:

HTTPS 1.1 GET https://api.myregion-sagex3.com/v1/token/authorise
client_id=clientID
scope=api.dataDelivery
customer=https://x3.customer.com
redirect_uri=https://3rd.app.com/callback
state=1234

The browser will direct the X3 user to the pending application approval with scope page. They can then accept or reject the request.
To accept the request, the X3 user must select which folder(s) the App can access. See FAQs for more about folders.
If the request is accepted, the App is notified by callback – for example:
```
HTTPS 1.1 POST https://3rd.app.com/callback
authorizationCode=<accesscode>
state=1234
endpoint=https://api.customerregion-sagex3.com/v1
```
Note: When the regional API endpoint you are using is not associated to the X3 configuration, a parameter called endpoint will be present in the callback. Your App must use this endpoint for future calls.

When your App is called back with the Access Code, it can call the Token API to exchange this code for tokens. For example:

HTTPS 1.1 POST https://api.customerregion-sagex3.com/v1/token
// body content in JSON format
{
   "code"="accesscode",
   "client_id" : "clientID",
   "client_secret": "clientSecret",
   "grant_type":  "authorization_code",
   "redirect_uri" : "https://3rd.app.com/callback"
}

Two tokens are returned:
- One access token, which is usable for 5 minutes (You’ll need to get a new access after this time, by making call to the token endpoint with your refresh token.).
- One refresh token, which is usable for 30 days and is reissued every time you get the new access token (Your access will be disabled after this time, and you’ll have to restart the pairing process.).
```
{
   "access_token":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.TTTTTTTTTTTTTTTTTTTTTT",
   "scope":"api.dataDelivery folder.SEED",
   "token_type":"bearer",
   "expires_in":300,
   "refresh_token":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.RRRRRRRRRRRRRRRRRRRRRR",
   "refresh_token_expires_in":2678400
}
```

Make your API call!

For example, to get a list of all available X3 folders using cURL:

curl -H "Authorization: Bearer XXXXXXX" https://api.customerregion-sagex3.com/v1/folders

If you chose 2 folders, ‘SEED’ and ‘X3’ in the pairing step, the answer would be:

{
  "folders": [
     {
         "name": "SEED",
         "$urls": {
           "dataDelivery": "https://api.customerregion-sagex3.com/v1/datadelivery/SEED/",
         }
     },
     {
         "name": "X3",
         "$urls": {
           "dataDelivery": "https://api.customerregion-sagex3.com/v1/datadelivery/X3/",
         }
     }
  ]
}