Introduction

Sage Active Public API V2 is secured by Oauth 2.0 with PKCE.

Note on Implementation Libraries:

The purpose of this documentation is to provide a detailed understanding of the OAuth 2.0 authentication process for the Sage Active Public API V2, step by step.
It is essential for developers to grasp these fundamentals to ensure a secure and effective integration.

However, to streamline the integration process and reduce the complexity of directly handling HTTP requests, responses, and security procedures, developers are encouraged to utilize well-established OAuth client libraries.
These libraries are designed for various programming languages and frameworks, offering a more developer-friendly way to implement OAuth integration.

Using such libraries can significantly simplify the process, handling the intricate details behind the scenes.
They manage the creation of URLs, secure handling of state parameters, and the exchange of the authorization code for access tokens.
This approach not only reduces the amount of code developers need to write but also enhances the security and reliability of the application by adhering to established best practices.

OAuth 2.0 with PKCE is an extension to the OAuth 2.0 protocol and is designed for public clients that cannot securely store client secrets, such as mobile, desktop or single page applications.
It enhances security by using a temporary secret created for each authorization request, mitigating the risk of an authorization code interception attack.

Access Token

For every request to Sage Active Public API V2, you must provide a valid Access Token in the authorization header.

Authorization: Bearer {Access Token}
Scopes

Your application will also need to authorize the necessary rights for it to function (scopes).

Warning! Only grant the necessary permissions.
For example, if your application does not plan to write data to Sage Active, it is not necessary to give the Write Sage Active Data permission.

Obtaining and Refreshing Access Tokens

The steps below detail the process for acquiring an access token for a mobile or desktop app, as well as utilizing a refresh token to secure a new token upon the expiration of the existing one.

Creating a Code Verifier and a Code Challenge

Before the authorization request, your mobile or desktop app must create a code verifier and a code challenge.

// Example of creating a code verifier and a code challenge
function base64URLEncode(str) {
    return str.toString('base64')
        .replace(/\+/g, '-')
        .replace(/\//g, '_')
        .replace(/=/g, '');
}
var verifier = base64URLEncode(crypto.randomBytes(32));

function sha256(buffer) {
    return crypto.createHash('sha256').update(buffer).digest();
}
var challenge = base64URLEncode(sha256(verifier));
Important Note on Base64 Encoding in Code Challenge Creation

It’s crucial to remember to encode the SHA256 encrypted value in base64 to ensure it’s correctly formatted for transmission.
The base64 URL encoding of the SHA256 encrypted value ensures it is compatible with URL standards, preventing issues related to character encoding and transmission.

1. Authorization Request

You must contact the authorization server of Sage Active by calling the authentication URL with the GET method and the required parameters, including the code_challenge and code_challenge_method:

Auth URL prod
Settings Value
response_type This parameter must always contain code
client_id The Client ID generated when creating your app
scope The required permissions for your application separated by a space %20:

  • RDSA - Reading accounting data
  • WDSA - Writing accounting data
  • offline_access - Access to refresh token, see below in this page: Renew a Refresh Token
redirect_uri The redirect url (Callback URL) you mentioned in your app
code_challenge The code challenge generated from the code verifier
code_challenge_method The transformation method used on the code verifier to create the code challenge, typically S256

img

If the call is successful, an HTTP response code 302 Found is returned and, in the provided authorization redirect URL, the following query parameters are returned:

Sample of the redirection to your redirect url with the query parameters

`http://your-redirect-uri.com/callback?code=AQzASDZZqxxxx...&scope=RDSA WDSA offline_access&iss=https://{sbcAuthUrl}&state=1234`
Possible errors

2. Resend authorization code to get access token

If the previous call is successful, you then need to make a POST call to get the Token:

Access Token URL prod
body parameters Value
grant_type This parameter must contain authorization_code
code The code returned by the GET call described earlier.
redirect_uri The redirect url (Callback URL) you mentioned in your app
client_id The Client ID that was generated when creating your app
code_verifier The code verifier generated earlier

If permission is granted, the response will return:

Sample of response

{
  access_token: "eyJhbGciOiJSUzI1NiIsImtpZCI6IjEyNTA2QjNGOTFFRxxxxxxxxxxxxx"
  expires_in: 28800
  refresh_token: "DF6FD016916A1263xxxxxxxxx"
  scope: "RDSA WDSA offline_access"
  token_type: "Bearer"
}
Remarks
Possible errors


3. Renew a Refresh Token

You can use renewing an access token to get a new access token if the current token has expired.
This means that your users are not required to authorize your application each time you request a new token.

Access Token URL prod
Settings Value
grant_type Must contain refresh_token
refresh_token Must contain the value of refresh_token returned by the Get Access Token response.
client_id The Client ID that was generated when creating your app

If permission is granted, the response will return, among other things:

Offline Access

This authentication service requires the offline_access scope to grant the use of refresh tokens.
This scope allows your application to obtain new access tokens without the need for user intervention when the current token expires.
To request offline access, include the offline_access scope when making your authorization request:

Settings Value
scope The required permissions for your application separated by a space %20:

  • RDSA - Reading accounting data
  • WDSA - Writing accounting data
  • offline_access - Access to refresh token

By adding offline_access to the list of requested scopes, the authorization server will issue a refresh token along with the access token, allowing your application to refresh the access token automatically when needed.

Do not forget that to renew the access token, you must exploit the refresh_token by sending a request with the grant_type refresh_token.
More info :


Revoke a Refresh Token

You can revoke a refresh token so that it is no longer valid for obtaining new access tokens.

Please note that you cannot revoke access tokens, they are valid for their lifetime.

Once a refresh token is revoked, it can no longer be used to obtain a new access token, so when the current access token expires, the user will need to log in again to access the application.

Revoke Token URL prod
Settings Value
token The value of the refresh_token you wish to revoke
client_id The Client ID that was generated when creating your app

If the operation was successful you will get a response with HTTP status 200.

Session Termination (Logout)

The process described here allows you to effectively log out a user by invalidating the refresh token, ensuring it can no longer be used to generate new access tokens.

When the refresh token is invalidated, any existing access tokens will remain valid until their set expiration but cannot be renewed. Consequently, the user will be prompted to re-authenticate once the access token expires.

Hereʼs how to perform the logout process:

Logout URL production

To complete the logout, follow these query parameters:

Settings Value
client_id The Client ID obtained during your application registration.
returnTo The logout URL listed in your application’s Logout URIs field within the associated solution.

img

Additionally, ensure to clear any stored access and refresh tokens from the client’s local storage to maintain security and prevent unauthorized use of stale tokens.