Authentication for Regular Web Applications

In order to obtain a Bearer Token from a Web application, you need to implement the Authorization Code OAuth 2.0 grant flow (defined in RFC 6749, section 4.1). It is a flow where the browser receives an Authorization Code from Sage ID and sends this to your Web application, then, your Web application interacts again with Sage ID and exchange the Authorization Code for an Access Token, and optionally a Refresh Token. Your Web application can now use this Access Token to call the Sage 200 API on behalf of the user.

This OAuth 2.0 flow follows these steps:

1. Your Web application initiates the flow and redirects the browser to Sage Id (specifically to the /authorize endpoint), so the user can authenticate.
2. Sage ID authenticates the user (via the browser). The first time the user goes through this flow a consent page will be shown where the permissions are listed that will be given to the application.
3. Sage ID redirects the user to your Web application, specifically to the redirect_uri, as specified in the /authorize request with an Authorization Code in the querystring (code). It is important to note that the redirect_uri must match with the Callback URL given in the registration process.
4. Your web app sends the Authorization Code to Sage ID and asks to exchange it with an Access Token and optionally a Refresh Token. This is done using the /oauth/token endpoint. When making this request, your Web application authenticates with Sage ID, using the Client Id and Client Secret.
5. Sage ID authenticates your Web application, validates the Authorization Code and responds back with the token.
6. Then, your Web application can use the Access Token to call the Sage 200 API on behalf of the user.
   
   

How to Implement it

In the next points, we will work through the steps needed in order to implement it: get the user’s authorization, get a token and access the Sage 200 API using the token.

1. Get the User’s Authorization

To begin an Authorization Code flow, your Web application should first send the user to the authorization URL:

<a href="https://id.sage.com/authorize?audience=861692d/sage200nc.sage.com/api&scope=openid email profile Sales:ReadWrite offline_access&response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_CALLBACK_URL&state=YOUR_OPAQUE_VALUE
 ">
  Sign In
</a>

The state parameter is an opaque value the application adds to the initial request that Sage ID includes when redirecting back to the application. This value must be used by the application to prevent CSRF attacks.

2. Exchange the Authorization Code for an Access Token

Now that you have an Authorization Code, you must exchange it for an Access Token that can be used to call the Sage 200 API. Using the Authorization Code from the previous step, you will need to POST to the Token URL:

var client = new RestClient("https://id.sage.com/oauth/token");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/json");
request.AddParameter "application/json", "{\"grant_type\":\"authorization_code\",\"client_id\": \"YOUR_CLIENT_ID\",\"client_secret\": \"YOUR_CLIENT_SECRET\",\"code\": \"YOUR_AUTHORIZATION_CODE\",\"redirect_uri\": \"https://YOUR_APP/callback\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

The response contains access_token, refresh_token, id_token, and token_type values, for example:

{
  "access_token": "eyJz93a...k4laUWw",
  "refresh_token": "GEbRxBN...edjnXbL",
  "id_token": "eyJ0XAi...4faeEoQ",
  "token_type": "Bearer"
}

Note that refresh_token will only be present in the response if you included the offline_access scope.

3. Call the Sage 200 API

Once you have the access_token you can use it to make calls to the Sage 200 API, by passing it as a Bearer Token in the Authorization header of the HTTP request:

// Use the Access Token to make Sage 200 API calls
$('#get-appointments').click(function(e) {
  e.preventDefault();

  $.ajax({
    cache: false,
    url: "https://sage200.sage.es/api/sales/products",
    headers: { "Authorization": "Bearer " + access_token }
  });
});

4. Get a new Access Token

If you have a refresh_token, you can call the /oauth/token endpoint using the refresh_token grant type, and the refresh token string, to obtain a new access token.

var client = new RestClient("https://id.sage.com/oauth/token");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "x-www-form-urlencoded");
request.AddParameter("application/json", "grant_type=refresh_token&refresh_token=REFRESH_TOKEN&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

The response contains access_token, expires_in, id_token, and token_type values.