Skip to content
Developerhome

Authentication Guide

  Less than to read

Starting a new app?
Use the latest version of Sage Business Cloud Accounting API by signing up at https://developer.sage.com/api/accounting.

Authentication

This section explains how to use OAuth 2.0 to allow users to authorize your application to access their data without sharing their actual login details.

With every API request, you must supply a valid Access Token within the Authorization Header and the resource_owner_id within the X-Site header:

Authorization:  Bearer ‹‹Access Token››
X-Site: ‹‹resource_owner_id››

Obtain an Access Token and resource_owner_id

The steps outlined here explain how to obtain the access token and resource_owner_id and how to use the refresh token to get a new access token if the current one has expired. You may find it useful to refer to the API Sample Solutions to see examples of this.

Authorization request

Redirect to the authorization server https://www.sageone.com/oauth2/auth/central with the relevant URL query parameters:

Required params

  • client_id Your application Client ID.
  • response_type The type of response. This is always code.
  • redirect_uri Your application callback URL. This is where your users will be sent after authorizing.

Optional params

  • scopes Lets you specify the type of access to allow. Can be [“readonly”] or [“full_access”].
  • state A string used to protect against CSRF attacks. Although state is optional, we recommend including this. This should be a string that cannot be guessed. Note: If the value of the state parameter returned in the response does not match the state that was provided in the original request, it does not originate from the original request and you must not continue.

Example redirect URL

https://www.sageone.com/oauth2/auth/central?response_type=code&client_id=4b64axxxxxxxxxx00710&redirect_uri=https://myapp.com/auth/callback&scope=full_access&state=4Whsv35d82bdbay6

When this endpoint is hit, the user is prompted to sign in to Accounting and asked if they want to authorize your application.

If the user allows access to your application, they are redirected to the callback URL along with an authorization code and the relevant country code which can be read from the response:

GET /auth/callback?code=12a0f9c12cxxxxxxxxxxxxxxx92a48cc1f237ead&country=ca

Possible errors

Error Description
access_denied This error occurs when the user chooses not to authorise your application.
invalid_request This error occurs when a required parameter is missing, invalid or provided more than once.
invalid_scope This error occurs when the scope provided is invalid or unknown. You should ensure that scope in your request is either readonly or full_access.
server_error This generic error occurs when the authorization server encounters something unexpected that prevents it from fulfilling the request.
temporarily_unavailable This error occurs when the authorization server is unavailable. We recommend waiting for 10 minutes before retrying.
unauthorized_client This error occurs when the client is not authorized to perform this action. This may be due to an incorrect client_id value.
unsupported_response_type This error occurs when the authorization server does not support the method being used to request the code. You should ensure that the response_type in your request is code.

Exchange the authorization code for the access token and resource_owner_id

To exchange the authorization code for an access token and resource_owner_id, you should now make a POST request to the relevant token endpoint for the country provided in the auth response:

Country code Token endpoint
CA https://oauth.na.sageone.com/token
DE https://oauth.eu.sageone.com/token
ES https://oauth.eu.sageone.com/token
FR https://oauth.eu.sageone.com/token
GB https://app.sageone.com/oauth2/token
IE https://app.sageone.com/oauth2/token
US https://oauth.na.sageone.com/token

Required parameters

  • client_id Your application Client ID.
  • client_secret Your application Client Secret.
  • code The authorization code provided in the response from the previous step.
  • grant_type This must be authorization_code.
  • redirect_uri Your application callback URL.

Example request

POST /token HTTP/1.1
Host: oauth.na.sageone.com

client_id=4b64axxxxxxxxxx00710&
client_secret=iNumzTxxxxxxxxxxhVHstrqWesH8tm9&
code=12a0f9c12cxxxxxxxxxxxxxxx92a48cc1f237ead&
grant_type=authorization_code&
redirect_uri=https://myapp.com/auth/callback

The response includes the access token and resource_owner_id:

{
  "access_token": "cULSIjxxxxxIhbgbjX0R6MkKO",
  "scopes": "full_access",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "b06b13xxxxxa275f08bfb57a3",
  "resource_owner_id": "ffRteb5wuy34wtsvghgGFreE7624Gvgh"
}

 Access tokens are currently 40 characters long, but this may change in the future. Please reserve up to 2048 characters in you data storage to be ready for future changes.

Possible errors

Error Description
invalid_request This error occurs when a required parameter is missing, invalid or provided more than once.
invalid_grant This error occurs when the grant_type provided is invalid or unknown. This error also occurs when the refresh token is expired or revoked.
invalid_client This error occurs when the client cannot be authenticated. For example, if the client_id or client_secret are incorrect or invalid.
unauthorized_client This error occurs when the client is not authorized to use the specified grant_type.
unsupported_grant_type This error occurs when the authorization server does not support the grant_type specified. You should ensure that the grant_type in your request is authorization_code or refresh_token.

Renew an Access Token

You can use the refresh token to obtain a new access token if the current one has expired.

This means that your users aren’t required to authorize your application every time you request a new token.

Send a POST request to the relevant token endpoint for the user’s country:

Country code Token endpoint
CA https://oauth.na.sageone.com/token
DE https://oauth.eu.sageone.com/token
ES https://oauth.eu.sageone.com/token
FR https://oauth.eu.sageone.com/token
GB https://app.sageone.com/oauth2/token
IE https://app.sageone.com/oauth2/token
US https://oauth.na.sageone.com/token

Required parameters

  • client_id Your application Client ID.
  • client_secret Your application Client Secret.
  • grant_type This must be refresh_token.
  • refresh_token The refresh token provided in the response from the previous step.

Example request

POST /token HTTP/1.1
Host: oauth.na.sageone.com

client_id=4b64axxxxxxxxxx00710&
client_secret=iNumzTxxxxxxxxxxhVHstrqWesH8tm9&
grant_type=refresh_token&
refresh_token=b06b13xxxxxa275f08bfb57a3

The response includes the new access token and a new refresh token:

{
  "refresh_token": "b0dfbxxxxx2ccf531",
  "expires_in": 3600,
  "scopes": "full_access",
  "access_token": "51913xxxxx9180d2",
  "token_type": "Bearer",
  "resource_owner_id": "ffRteb5wuy34wtsvghgGFreE7624Gvgh"
}

Revoke an Access Token

You revoke an access token so it is no longer valid for making requests.

Once revoked, a user will need to authourise again to generate a new valid access token

Send a POST request to the relevant revoke endpoint for the user’s country:

Country code Token endpoint
CA https://oauth.na.sageone.com/revoke
DE https://oauth.eu.sageone.com/revoke
FR https://oauth.eu.sageone.com/revoke
GB https://app.sageone.com/oauth2/revoke
IE https://app.sageone.com/oauth2/revoke
US https://oauth.na.sageone.com/revoke

Required parameters

  • token The access token you wish to revoke.
  • client_id Your application Client ID.

Example request

POST /revoke HTTP/1.1
Host: oauth.na.sageone.com

client_id=4b64axxxxxxxxxx00710&
token=8etep08exxxxxxxxxxxxxxxxxxxxxxxx854de520c
On success, an empty 204 response will be returned