You are currently using a browser that we do not support. For a better experience please upgrade your browser. Find out how.

Sage One Developer Self Service


 

Authentication

This section explains how to use OAuth 2.0 to allow Sage One users to authorize third party applications to access their data without sharing their actual login details.

Watch the screencast

To see this in action, take a look at our API Authentication screencast.
 

Overview

When you register your client application for the Sage One API, you are provided with:

  • A client_id
  • A client_secret
  • A signing_secret
Note: You must store these securely and DO NOT share them with anyone. You must not check this information into source control.

The following diagram shows the process for the OAuth2 handshake:

Sage One OAuth Workflow

 

Authorization request

Redirect to the Sage One authorization server:

https://www.sageone.com/oauth2/auth

Required parameters

  • response_type - This is the type of response that you expect to receive. This is always code.
  • client_id - The client id you received from Sage One when you registered.
  • redirect_uri - The callback URL. This is where your users will be sent after authorizing.

Optional parameters

  • scope - Lets you specify the type of access to allow. Can be readonly or full_access. Read only does not allow you to modify any Sage One data. If you do not provide this parameter, the default is 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

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


&scope=full_access

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

Note: This can only be authorized by the business owner (the user that created the Sage One subcription).

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

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

The authorization code expires after 60 seconds.

Possible errors

Error Description
access_denied This error occurs when the Sage One business 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.
 

Access token

You should now request an access token in exchange for the authorization code.

To do this, send a POST request to:

https://api.sageone.com/oauth2/token

Required parameters

  • client_id - The client id you received from Sage One when you registered.
  • client_secret - The client secret you received from Sage One when you registered.
  • code - The authorization code provided in the response from the previous step.
  • grant_type - The type of grant the code relates to. Either authorization_code or refresh_token.
  • redirect_uri - The callback URL used to get the authorization code.

Example request

POST /oauth2/token HTTP/1.1
Host: api.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:

{
  "access_token": "cULSIjxxxxxIhbgbjX0R6MkKO",
  "scope": "full_access",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "b06b13xxxxxa275f08bfb57a3"
}
Info: The access token expires after 1 hour. You can use the refresh token to obtain a new access token if it has expired.

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.
 

Using the refresh token

During the authorization exchange, you are issued with an access token and a refresh token and you must include the access token in every API call.

The access token expires after 1 hour.

You can use the refresh token to obtain a new access token without the user having to sign in again to allow access.

To do this, send a POST request to:

https://api.sageone.com/oauth2/token

Required parameters

  • client_id - The client id you received from Sage One when you registered.
  • client_secret - The client secret you received from Sage One when you registered.
  • refresh_token - The refresh token provided in the response from the previous step.
  • grant_type - This must be refresh_token.

Example request

POST /oauth2/token HTTP/1.1
Host: api.sageone.com

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

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

{
  "refresh_token":"b0dfbxxxxx2ccf531",
  "expires_in":3600,
  "scope":"full_access",
  "access_token":"51913xxxxx9180d2",
  "token_type":"Bearer"
}

Next steps

Signing your requests