Skip to content
Developer home
X3

Make your first API call with complete parameters detail

  Less than to read

  1. 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.

    security profile

  2. 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
    
  3. The browser will direct the X3 user to the pending application approval with scope page. They can then accept or reject the request.

    Scope

  4. To accept the request, the X3 user must select which folder(s) the App can access. See FAQs for more about folders.

    Folder

  5. 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.

  6. 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"
    }
    
  7. 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
    }
    
  8. 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/",
             }
         }
      ]
    }