Authenticate with the Sage 200 API

The API uses the OAuth 2.0 standard for authentication. OAuth 2.0 is a widely recognised framework for authentication and is globally used in APIs. You can read more about OAuth 2.0 here.

If you need Information or support on setup and configuration of the Native API, using Microsoft Azure Active Directory tunnelling, please find our guide here.

Terminology

Before learning more about the details of the authorization process, make sure that you are familiar with some of the key terms used in this guide:

• Client: Any app that wants access to a sites data. A user must grant permission before the client can access any data.
• API: The Sage 200 REST API, which the client can use to read and modify site data.
• Mobile Client: Mobile and Desktop applications are classed as a public client types as they would need to store the client and secret locally, and securely, which are then used as part of the Sage ID user authentication process. This is potentially less secure as the client and secret would need to be distributed with the compiled applications. To improve security, a temporary certificate is issued by Sage ID to secure any communication between the application and Sage ID.
• Web Client: Web based applications that store the Client and Secret keys on a server are classed as Confidential Clients. They are more secure because only the server has access to these keys; they are not distributed to end users.

The OAuth Flow

Sage uses OAuth 2.0’s authorization code grant flow to issue access tokens on behalf of users.

1. The user makes a request use your application with Sage.
2. The app redirects to Sage ID to load the OAuth grant screen and requests the required scopes.
3. Sage displays a prompt to receive authorization and prompts the user to login if required.
4. The user consents to the scopes and is redirected to the redirect_uri.
5. The app makes an access token request to Sage including the client_id, client_secret, and code.
6. Sage returns the access token and requested scopes.
7. The app uses the token to make requests to the Sage API.
8. Sage returns the requested data.

Step 1: Get Client Credentials

You need to retrieve an ID to identify the client during the authorization process, if creating a web application, you will also receive a secret key.

You can obtain these by submitting a credential request form.

Step 2: Ask for permission

When the user chooses to access their sites from within your application, they will be asked to sign into When this endpoint is queried, the user is prompted to sign into with their Sage ID and asked if they want to authorise the application. If the user allows access to your application, they are redirected to the redirect URL along specified in the request with an authorization code which can be read from the response.

Sage 200 displays a prompt to receive authorization from the user:

To show the prompt, redirect the user to the following URL with the query parameters defined below:

https://id.sage.com/authorize?audience=s200ukipd/sage200&client_id={clientId}&response_type=code&redirect_uri={redirect}&scope={scopes}&state={state}

{clientId} The app’s API client ID, see Get Client Credentials.

{redirect} The URL to which a user is redirected after authorizing the client. The complete URL specified here must be added to your app as an allowed redirection URL, as defined within the credentials request form.

{scopes} A space-separated list of scopes. For relevant access pass the following “openid profile email offline_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.

Step 3: Confirm Permission

When the user signs into their account within the prompt, they are redirected to the client server using the redirect as specified above. The authorization_code and state are passed in this confirmation redirect.

https://example.org/some/redirect/uri?code={authorization_code}&state={state}

Before you continue, make sure your app performs the following security check. If any of the checks fails, your app must reject the request with an error, and must not continue.

The value of the state parameter returned must match the state you provided in the original request. If this 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.

If all security checks pass, then you can exchange the authorisation code for a permanent access token by sending a request to the token endpoint:

POST https://id.sage.com/oauth/token

In your request the following parameters must be provided in the request body:

client_id The API key for the app, as defined in the Partner Dashboard.

client_secret The API secret key for the app, as defined in the Partner Dashboard.

redirect_uri A URL which has been added to your app as an allowed redirection URL.

code The authorization code provided in the redirect.

grant_type authorization_code

The server responds with an access token in the following format:

{

"access_token":"testValue",

"refresh_token":" testValue",

"id_token":" testValue",

"scope":"openid offline_access",

"expires_in": 28800,

"token_type":"Bearer"

}

The following values are returned:

access_token: An API access token that can be used to access the sites data. Clients should store the token somewhere secure to make authenticated requests to a sites data.

refresh_token: is used to obtain new access and refresh tokens when the access token expired. Users specify the expiry time when submitting their credential request form with a maximum of 90 days. Users will have to freshly authorize your app if you do not refresh your tokens within the specified time.

scope: The list of access scopes that were granted to the application and are associated with the access token.

token_type: This is always bearer.

expires_in: Informs you about the lifetime of the access token, which is 28800 seconds/8 hours

Id_token: ID Token value associated with the authenticated session.

Step 4: Renew an Access Token

When an access token expires, your application can be configured to either have the user login to requests another access token, or the refresh token can be used to generate a new access token without user interaction up to the lifetime of the refresh token. When you request a new access token, this will generate a new access/refresh token pairing for you to use.

To renew your access token, send a POST request to the following URL:

POST https://id.sage.com/oauth/token

In your request the following parameters must be provided in the request body:

client_id The API key for the app, as defined in the Partner Dashboard.

client_secret The API secret key for the app, as defined in the Partner Dashboard.

redirect_uri A URL which has been added to your app as an allowed redirection URL.

refresh_token The refresh token which was returned as part of your access token request.

Grant_type refresh_token

The server responds with an access token in the following format:

{

"access_token":"testValue",

"refresh_token": "testValue",

"id_token": "testValue",

"scope":"openid profile email offline_access",

"expires_in": 28800,

"token_type":"Bearer"

}

Step 5: Making authenticated requests

After the client has obtained an API access token, it can now make authenticated requests to the REST API. Note without a valid access token any request will be denied.

These requests use HTTP (Hypertext Transfer Protocol) methods (GET, POST, PUT, DELETE) to determine the request functionality.

The Base URL for your request will differ based on the Sage 200 application you are integrating with.

For Sage 200 Professional you need to ensure the following Base URL is being used:

https://api.columbus.sage.com/uk/sage200extra/accounts/

For Sage 200 Standard Online, this would be:

https://api.columbus.sage.com/uk/sage200/accounts/

These requests must be accompanied with the following headers:

ocp-apim-subscription-key Your Developer Subscription Key.

X-Company The company_id of the Company.

X-Site The site_id value of the Site.

Authorization A valid access token.

Content-Type application/json.

Your access token should be sent in the following format:

Bearer {{AccessToken}}

The following is an example request to retrieve all customers from a Sage 200 professional site:

GET https://api.columbus.sage.com/uk/sage200extra/accounts/v1/customers

The server will respond with the following response:

[

{

"id": 27828,

"reference": "ABS001",

"name": "ABS Garages Ltd",

"short_name": "ABS Gara",

"balance": 2464.16,

"on_hold": false,

"account_status_type": "AccountStatusActive",

"currency_id": 2103,

"exchange_rate_type": "ExchangeRateSingle",

"telephone_country_code": "44",

"telephone_area_code": "0191",

"telephone_subscriber_number": "254 5909",

"fax_country_code": "44",

"fax_area_code": "0191",

"fax_subscriber_number": "254 5907",

"website": "www.sage.co.uk",

"credit_limit": 4000.00,

"country_code_id": 13,

"default_tax_code_id": 1729,

"vat_number": "GB745 4584 68",

"duns_code": "",

"analysis_code_1": "Trade",

"analysis_code_2": "George",

"analysis_code_3": "Tyne & Wear",

"analysis_code_4": "",

"analysis_code_5": "",

"average_time_to_pay": 319,

"value_of_current_orders_in_sop": -36.00,

"date_time_updated": "2016-07-08T15:28:48.66"

}

]

What’s Next

Information on who responsible for each area of a Sage API deployment can be found here.

Frequently Asked Questions

For a list of frequently asked question regarding the Sage 200 API, please see here.

Getting Started with Postman

This guide provides steps to making API request to the Sage 200 RESTful API via Postman, and can be found here.

Developer Community

Get help and support, share knowledge, thoughts and ideas, and keep updated with any upcoming events here.