Authentication
BETA
Introduction
Sage Active Public API V0 is secured by Oauth 2.0.
OAuth 2.0., short for “Open Authorization”, is an open standard protocol that allows authorization for secure API access.
It is often used to allow users to grant third-party access to their resources without sharing their passwords.
OAuth 2.0 allows a user to authorize an application to access their resources without sharing their login credentials.
Instead, the user grants access by authenticating with their login credentials and authorizing the application to access their resources.
OAuth 2.0 provides a secure way for applications to access resources on behalf of a user without exposing the user’s login credentials.
To avoid the risk of third parties intercepting and misusing these data, authorization for data transfers between Sage Active Public API V0 and the Sage Active application is therefore necessary.
Access Token
For every request to Sage Active Public API V0, you must provide a valid Access Token in the authorization header.
Authorization: Bearer {Access Token}
An access token belongs to a single user account in Sage Active. This means that a user of your application will be able to access all of the data of their companies (accounting files) that are authorized in the Sage Active interface. In Sage Active, a user can indeed have access to one or more companies. They must first select the company in order to then access the data of that company.
Scopes
Your application will also need to authorize the necessary rights for it to function (scopes).
For example, if a mobile app asks you for permissions to access contacts, the camera, the microphone, the phone, storage, etc., your application will need to only authorize access to the resources it needs.
Warning! Only grant the necessary rights, for example, if your application does not plan to write data to the accounting, it is not necessary to give the Write Sage Active Data right.
Obtain a Refresh Token
The following steps explain how to obtain an access token for a web application and how to use the token refresh (Refresh Token) to obtain a new token if the current one has expired.
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:
| Settings | Value |
|---|---|
| response_type | This parameter must always contain code |
| state | A value of your choice to prevent cross-site request forgery |
| client_id | The Client ID that was generated when creating your app from the developer path. |
| scope | The required permissions for your application separated by a space %20:
|
| redirect_uri | The redirect url (Callback URL) you mentioned in your app. |
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 inscopeare 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 iscode.
2. Resend authorization code to get access token
If the call is successful, an HTTP response code 302 Found is returned and the response returns a header field (Response Headers) named location containing:
- the redirect url sent in the GET,
- an authorization code assigned by the authentication server,
- the
statevalue sent in the GET.
Response Headers
location: "{url de redirection}?code={code d'autorisation}&state={valeur state}"
You then need to make a POST call to get the Token:
| Settings | 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 |
| client_secret | The Client Secret that was generated when your app was created |
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 V0expire_in: the duration in seconds during which the access token is granted,token_type: always containsBearer,scope: the rights that have actually been authorized,refresh_token: The refresh token value.
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: thegrant_typeparameter 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 incorrectclient_idorclient_secretvalue.unauthorized_client: The client is not authorized to use the specifiedgrant_type.unsupported_grant_type: The authorization server does not support the specifiedgrant_type. You need to make sure thegrant_typein your request isauthorization_codeorrefresh_token.
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.
| 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 |
| client_secret | The Client Secret that was generated when your app was created |
If permission is granted, the response will return, among other things:
access_token: the value of the new access tokenrefresh_token: the value of the new refresh token
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:
|
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.
Don’t 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.
| Settings | Value |
|---|---|
| token | The value of the refresh_token you wish to revoke |
| customer_id | The Client ID that was generated when creating your app |
| client_secret | The Client Secret that was generated when your app was created |
If the operation was successful you will get a response with HTTP status 200:
{
"success": "ok"
}