Authentication Guide

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

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

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

• 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

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

• 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:

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