Authentication

This section explains how to use OAuth 2.0 to allow Sage Accounting 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 Applications to see examples of this.

1. Authorization request

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

Required params

Optional params

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 Sage 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

2. 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:

Required parameters

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

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:

Required parameters

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:

Required parameters

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