Make your first API calls

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 = businessDomain.ALL api.graphQL 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":"businessDomain.ALL api.graphQL folder.SEED",
        "token_type":"bearer",
        "expires_in":300,
        "refresh_token":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.RRRRRRRRRRRRRRRRRRRRRR",
        "refresh_token_expires_in":2678400
    }

Make your API calls!

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": {
                    "dataService":  "https://api.customerregion-sagex3.com/v1/service/X3CLOUDV2_SEED/api"
                }
            },
            {
                "name": "X3",
                "$urls": {
                    "dataService": "https://api.customerregion-sagex3.com/v1/service/X3CLOUDV2_X3/graphQL"
                }
            }
        ]
    }

You can now get a list of customers by GraphQL API using cURL:

    curl -H "Content-Type: application/json" -H "Authorization: Bearer XXXXXXX" -d '{"query":"{\n  sage {\n    x3BusinessPartners {\n      customer(first: 2) {\n        edges {\n          node {\n            code\n            companyName\n          }\n        }\n      }\n    }\n  }\n}","variables":null}' -X POST  "https://api.customerregion-sagex3.com/v1/service/X3CLOUDV2_SEED/api"

The answer would be:

    {
        "data": {
            "sage": {
                "x3BusinessPartners": {
                    "customer": {
                    "edges": [
                        {
                            "node": {
                                "code": "AE1",
                                "companyName": "An Enterprise 1"
                            }
                        },
                        {
                            "node": {
                                "code": "AE2",
                                "companyName": "An Enterprise 2"
                            }
                        }
                    ]
                    }
                }
            }
        },
        "extensions": {}
    }