Skip to content
Developerhome

How to get access to the tenant

  Less than to read

You need to perform an HTTP POST request on the token API with the following JSON code:

body: {
    "clientId": "<Client ID FROM APP-REGISTRY>", 
    "clientSecret": "<Secret Key from APP-REGISTRY>",
    "tenantId": "<TENANT ID>" 
}

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

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.
  • A refresh token that allows you to renew your access token when the token expires. The refresh token is valid for 1 hour.
  • There are different URLs that you can use to consume the different services:
    • graphQL: The URL to perform GraphQL requests. You cannot hardcode this link in your application because it can vary from one tenant to another. To perform GraphQL requests on a specific tenant, you need to dynamically follow urls.graphQl in the token API.
    • asyncContextUploadUrl and asyncContextErrorUrl: Used for integration with on-premise ERPs. You can ignore this endpoint.
    • websocketUrl: The URL to connect to the WebSocket endpoint. For now, you can ignore this endpoint.
    • refreshToken: The URL to refresh your access token.
    • invalidateToken: The URL to invalidate your access and refresh tokens.

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

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 need to renew it.

To renew your access token, you need to consume the API URL defined in urls.refreshToken with your current refresh as a bearer token like in the example below

HTTP POST https://api.eu.erp.sage.com/v1/token/renew 
    HEADERS 
        Authorization: Bearer <refresh-token>

The response is the same as when you request an initial token.

Once consumed, your refresh token is no longer valid. You need to replace it with the one provided in the response of the refresh token API call. This gives you new access and refresh tokens.

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>;refreshToken=<refresh-token> 

You can invalidate both tokens at the same time or individually.

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.