Authentication (mobile or desktop app)

Introduction

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

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).

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.

• Code Verifier: A cryptographically random string generated by your mobile or desktop app.
• Code Challenge: The code verifier transformed using the method you choose, typically S256.

// 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));

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:

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:

• code: This is the authorization code which the client will exchange for an access token.
• scope: This indicates the permissions granted by the user. The scopes here are RDSA WDSA offline_access, which might stand for different access levels or permissions within the application and the ability to obtain refresh tokens (indicated by offline_access).
• iss: This denotes the issuer of the response, can be used to validate the authenticity of the authorization response
• state: Typically included inauthorization requests and responses to maintain state between the client and the authorization server.
  This mechanism is used for CSRF (Cross-Site Request Forgery) protection and to restore the previous state of the client application after the authorization flow completes.

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

Possible errors

• access_denied: Sage Active refuses to authorize your application.
• invalid_request: A required parameter is missing, invalid or provided multiple times.
• invalid_scope: The rights mentioned in scope are incorrect or insufficient.
• server_error: The authorization server encounters an unexpected error that prevents it from responding to the request.
• temporarily_unavailable: The authorization server is not available. We recommend waiting 10 minutes before trying again.
• unauthorized_client: The client is not authorized to perform this action. This may be due to an incorrect client_id value.
• unsupported_response_type: The authorization server does not support the method used to request the code. You need to make sure the response type in your request is code.
  
  

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:

If permission is granted, the response will return:

• access_token: the access token value used for authentication of your requests to Sage Active Public API V2
• expire_in: the duration in seconds during which the access token is granted,
• token_type: always contains Bearer,
• scope: the rights that have actually been authorized,
• refresh_token: The refresh token value, provided only if offline_access scope has been requested and granted, which is used to obtain new access tokens when the current access token expires.

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

Remarks

• Make sure you don’t share this Access Token and don’t store it in an unsafe location.
• Reserve up to 2048 bytes in your data storage for this Access Token
• Also reserve up to 2048 bytes in your data storage for the Refresh Token.
• You should not share this refresh token or store it in an insecure location such as an unencrypted browser session.

Possible errors

• invalid_request: A required parameter is missing, invalid or provided multiple times.
• invalid_grant: the grant_type parameter mentioned is invalid or unknown, or the authorization code could be expired (after 60 seconds), already used or unknown, or the refresh token has expired or has been revoked.
• invalid_client: The client cannot be authenticated. This may be due to an incorrect client_id value.
• unauthorized_client: The client is not authorized to use the specified grant_type.
• unsupported_grant_type: The authorization server does not support the specified grant_type. You need to make sure the grant_type in your request is authorization_code or refresh_token.

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.

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

• access_token: the value of the new access token
• refresh_token: the value of the new refresh token

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.

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:

To complete the logout, follow these query parameters: