How to get access to the tenant

Less than 5 minutes to read

Once you’ve registered to http://app-registry.sage.com/ and have been granted access to the application, you can use the Token API to access the application.

To fetch an access token, you need the credentials from http://app-registry.sage.com/ and the Tenant ID you want to access.

The Token API gets you an access token that gives you access to the application.

The API endpoint is https://api.erp.sage.com/v1/token.

The API follows the standard OAuth2 Client Credentials Flow. This type of HTTP request involves the following parameters:

grant_type: Client credentials.
client_id: Client ID.
client_secret: Client secret.
scope: Specifies the tenant you want to access to. Corresponds to the Tenant ID.

The following is an example of a HTTP request following the OAuth2 Client Credentials Flow:

HTTP POST https://api.erp.sage.com/v1/token
    HEADERS
        content-type: application/x-www-form-urlencoded
    BODY
        grant_type=client_credentials&client_id=<Client ID FROM APP-REGISTRY>&client_secret=<Secret Key from APP-REGISTRY>&scope=tenantid%3A<TENANT ID>

The same type of HTTP request can also be performed with Postman.

If your application is allowed access to the tenant, an HTTP 200 response is returned.

The response from the API provides the following elements:

An access token to be used as an authorization bearer token in the different services. The access token is valid for 15 minutes.
There are different URLs that you can use to consume the different services:

asyncContextUploadUrl and asyncContextErrorUrl: Used for integration with on premise ERP. You can ignore this endpoint.
invalidateToken: Used to invalidate the access token.
websocketUrl: URL to connect to the websocket endpoint. For now, you can ignore this endpoint.
apps: One subsection for each application owned by the tenant you are connecting to.

graphQL: URL to perform GraphQL requests on the application.

If you use Postman, the response of the API includes the access token, URLs for graphQL, asyncContextUpload, asyncContextError, and websocket. It also includes the expiration date for the access token, as well as the corresponding tenant ID.

The following is an example of a response when the application is allowed access to the tenant:

{
    "access_token": "XXXXXX",
    "token_type": "Bearer",
    "urls": {
        "asyncContextUpload": "https://api.eu.erp.sage.com/v1/asyncContext/{AsyncContextId}/upload",
        "asyncContextError": "https://api.eu.erp.sage.com/v1/asyncContext/{AsyncContextId}/error",
        "websocket": "wss://websocket.eu.erp.sage.com",
        "invalidateToken": "https://api.eu.erp.sage.com/v1/token",
        "apps": {
            "sdmo": {
                "graphQL": "https://api.eu.erp.sage.com/v1/fwd/cluster-release/sdmo/api"
            },
            "shopfloor": {
                "graphQL": "https://api.eu.erp.sage.com/v1/fwd/cluster-release/shopfloor/api"
            }
        }
    },
    "expires_in": 300,
    "scope": "tenantid:Dz62IqY7R8o7W6oj_mreA"
}

If your credentials are invalid or if the tenant did not accept your application access, an HTTP 403 forbidden response is returned.

See more on how tenant administrator can allow access to your app in the Configure your tenant to accept incoming APIs page.

The access token is then used to access the tenant API. If you do not use Postman, you need to add the access token in a header like in the following example:

curl –h “Authorization: Bearer <theaccesstoken>” -d ‘{graphql request payload}’  https://api.na.sageintacctmanufacturing.com/v1/fwd/prd1/api

An access token has a lifetime of 15 minutes. You can request a new one by performing a new HTTP request. The response to the new request is the same as when you request an initial token.

For security reasons, it is recommended to invalidate tokens when you do not need them anymore. The URL to invalidate a token is the one provided in the urls.invalidateToken response.

HTTP DELETE https://api.eu.erp.sage.com/v1/token 
    HEADERS 
        x-tokens: accessToken=<access-token>

For developers familiar with swagger.io, Sage provides a file that displays the documentation in a more friendly and interactive way. For more information, see the API reference here.