Skip to content
Developerhome
Product homepage
Authentication Service

Onboard a desktop application

  Less than to read

An application installed on a user owned device. These applications are not considered trusted, therefore, they also must receive tokens from the ‘Sage Token Service’ and use them as part of a captcha process to confirm human interaction.

Before you can complete these steps your application must have been created in the Sage Authentication Service. The process for having this done is described here.

You can onboard and integrate a desktop application with any of our services through the REST API in 6 steps:

  • Retrieve a token from the Sage Token Service
  • Call Captcha Endpoint & Complete Captcha
  • Start creation of an organisation
  • Poll for completion and get the created organisation
  • Get an access token for the organisation
  • Create a company
  • Get an access token for the company

An organisation represents a Sage customer using a Sage product and Service Fabric services.

When you create an organisation, you receive a JSON payload. This contains the values that allow you to obtain a JSON Web Token (JWT). Use the JWT to authenticate your HTTP requests against the REST API.

A company represents any institution that belongs to the organization.

A company is always linked to a particular organisation. Depending on the country where you use the service, an organisation can have one or several companies.

Retrieve a token from the Sage Token Service

Send a POST request to the ‘Sage Token Service’ with the following headers and body.

**Please note this is not the documentation for the Sage Token Service, which is linked above, and the following are just given as illustrative examples. Please contact the team responsible for the Sage Token Service for more information.

Headers

POST /api/v1/requestToken
Host: sagetokenservice.com
Content-Type: application/json
x-provider:{app name}
x-application:sage.{app name}

Where:

  • POST /api/v1/requestToken is the endpoint where you send your request.
  • sagetokenservice.com is the request’s base URL.
  • {app name} is the name of an app supported by, and in the format accepted by Service Fabric. For example: sage.intacct.

Body

Below are examples of the request body that can be sent to the Sage Authentication Service. The first example is a bare minimum request body, the second gives a more verbose example of what can be included in the license data part of the request body.

{
  "clientData": {
    "PREPOP_ADMIN_EMAIL": "[email protected]"
  },
  "licenceData": {
    "serial": "ACTIVE"
  }
}

{
  "clientData": { "PREPOP_ADMIN_EMAIL": "[email protected]" },
  "licenceData": {
    "fileType": "License",
    "generationStamp": "2016-09-23T14:33:54Z",
    "partnerId": "",
    "licenseType": "NFR",
    "product": { "code": "1", "version": "11" },
    "policy": { "code": "ERPX3", "version": "1.0" },
    "serial": "106001000011",
    "validity": ["1970-01-01", "2023-06-01"],
    "sessionControl": "concurrent",
    "signature": "SIGNATURE",
    "signatureText": "SAGE SAS"
  }
}

Example Response

{
  "token": "e1890515-e5fd-40ad-8d00-bba156a5b051"
}

Call Captcha Endpoint & Complete Captcha

Once the t1 token was retrieved from the Sage Token Service the user needs to complete a captcha in order to exchange the t1 token for a t2 token that can be used to call the Sage Authentication Service.

Captcha Example

Headers

GET /auth-v1/captcha?payload={t1}&captcha=true
X-Application: {app name}

The Auth Service will redirect the user to a Captcha page to complete. When the user completes the Captcha a t2 token will be returned.

Example response

{
  "t2": "0969b85d-c63a-46cd-90ae-65821757f9e0"
}

Where:

  • t2 contains the t2 token that can be used to call the Sage Authentication Service’s Organisations endpoint. Use this token to create an organisation via the REST API.

Create an organisation

Send a POST request with the following headers and body.

This request does not synchronously create an organisation; an organisation will not be created and returned immediately. If your request is successful the creation process will begin and the t2 token will be returned. You’ll receive a JSON response like the one shown in the example response section.

Headers

POST /auth-v1/organisations HTTP/1.1
Host: api-money.sage.com
Content-Type: application/json
X-Application: {app name}
Authorization: {t2}

Where:

  • POST /auth-v1/organisations is the endpoint where you send your request.
  • api-money.sage.com is the request’s base URL.
  • {app name} is the name of an app supported by, and in the format accepted by Service Fabric. For example: sage.intacct.
  • {t2} is the t2 Token returned when the user completed the Captcha

Body

{
  "name": "{organisation name}",
  "sageCRMId": "{app serial number}",
  "primaryCountry": "{country code}",
  "adminEmail": "{admin email}",
  "defaultLanguage": "{language code}",
  "externalId": "{external ID}"
}

Where:

  • {organisation name} is the name for the organisation you want to create. For example: My organisation.

  • SageCRMId value is provided by Sage and is the unique identifier for the Sage customer in the CRM system holding customer details. This is used for various purposes, including providing aggregated management information and contacting the customer if problems occur.

    Make sure to submit the correct SageCRMId value. Providing the wrong SageCRMId value may prevent the integration from working properly.

  • {country code} is your country in the ISO 3166-1 Alpha-3 format. For example: GBR.
  • {admin email} is the app administrator’s contact email. Make sure you specify a valid email.
  • {language code} is the default language for your organisation in the ISO 639-1 format. For example: EN.
  • {external ID} is the unique organisation identifier. It’s used to identify the organisation in the consuming application. It is provided to the application in any notifications sent from the service.

Example response

If successful an HTTP Accepted 202 status code will be returned with the following body:

{
  "t2": "0969b85d-c63a-46cd-90ae-65821757f9e0"
}

Where:

  • t2 contains the t2 token that can be used to call the Sage Authentication Service’s Organisations endpoint. Use this token to check the creation status of an organisation via the REST API.

Poll for created organisation

Send a GET request with the following headers and URL parameter.

An organisation will be returned if/when created. You’ll receive a JSON response like the one shown in the example response section.

Headers

GET /auth-v1/organisations/poll{t2} HTTP/1.1
Host: api-money.sage.com
X-Application: {app name}

Where:

  • GET /auth-v1/organisations/poll is the endpoint where you send your request.
  • api-money.sage.com is the request’s base URL.
  • {t2} is the t2 Token returned in POST Organisations response.
  • {app name} is the name of an app supported by, and in the format accepted by Service Fabric. For example: sage.intacct.

Body

None

Example response

{
  "organisationId": "0969b85d-c63a-46cd-90ae-65821757f9e0",
  "name": "My organisation",
  "sageCRMId": "3c7071a3-ee44-1dda-c764-d3e09b1502dc",
  "primaryCountry": "GBR",
  "adminEmail": "[email protected]",
  "defaultLanguage": "EN",
  "externalId": null,
  "primarySigningKey": "GGWWFWWA059696B162774F469AA0B206B40AD7245CAC2A9E610898A4FCAC"
}

Where:

  • organisationID contains an automatically generated unique ID of the created organisation. Use this ID to retrieve or update the organisation via the REST API.
  • primarySigningkey contains the secret you will need to generate an X-Signature value in the next step. Read our generating an X-signature guide for more information.
  • name, SageCRMId, primaryCountry, adminEmail, defaultLanguage, externalId – These contain the values defined in your request body.

Get an access token for the organisation

To work with an organisation via the REST API, you need to obtain an access token and use it to sign your HTTP requests.

The token is generated using the organisation unique ID (organisationId). It allows you to work with that organisation only.

To work with another organisation you’ll need to obtain a new access token.

To get an access token, send a GET request with the following headers.

You’ll get an access token in the JSON response if your request is successful. Each access token expires after a certain amount of time. To obtain a new valid access token for the organisation, resend your GET request.

Headers

GET /auth-v1/accesstoken HTTP/1.1
Host: api-money.sage.com
X-Organisation-Id: {organisation ID}
X-Nonce: {unique value}
X-Signature: {signature}
X-Application: {app name}

Where:

  • GET /auth-v1/accesstoken is the REST API endpoint where you send your request.
  • api-money.sage.com is your request’s base URL.
  • {organisation ID} is the ID of the organisation you’re generating an access token for.
  • {unique value} is an arbitrary unique value, such as a GUID. In each HTTP request you must use a new value.
  • {signature} is the signature for your request. Read our generating an X-signature guide for more information.
  • {app name} is the name of an app supported by, and in the format accepted by Service Fabric. For example: sage.intacct.

For more information about this REST resource and its parameters, go to the Onboarding and authentication API reference.

Example response

An access token looks like:

{
  "jwt": "AAAAAAAAAAA.wtwwwnifjaoisdfafMC4wLjAiLCJvcmdhbmlzYXRpb25KKKKKKKJZCI6ImFiMWY3OGIyLTM4NGUtNGUyMC1iMzY2LTZmOTBiODc2M2U2ZSIsInNvdXJjZVByb2R1Y3QiOiJzYWdlLmJyYXppbC5vbmUiLCJraWQiOiI3NTdiNTBmZDhmNDYxODAyNTI2MTFiMDY2ODI2NTBiNDYyYmYyYmE4MzNkMzExYYwMDI3IiwiaXAiOiI4MS4xMjguMjMzLjIwMiIsImlzcyI6IndwYi1hdXRoIiwiY2hhbm5lbCI6Im9ubGluZS1jaGFubmVsIiwiZXhwIjoxNTU2MDE1Njc3LCJzZXJ2aWNlSWQiOiJ3cGItYXV0aC1zZXJ2aWNlIiwiaWF0IjoxNTU2MDE0NDc3fQ.afe3qfgewgpkhidaMgo_nmrrWMEeGvq5q2yFElgZ79AnjQ74yyt1WgXKn8gNH90RwdNXStozG2cTsg8PvPvM0lWV0sRZM3yVOJs2FvZp5aSzFuFq6m2xcjwkLxTys3x1Knx3oZkXTYMoEbI3_ZvwSvxV3DK2cNT888gsTXQuwgJstR2Qpud5abcJIY64-oVnshyuJrgO391n7FHCnn1Hm-9eSegLSIl0zJYN0xVYuT21iRxZk0sObZMC12FC0qNh2gdi-kOUMEdzkJ0iEYeDp4b3tFnUSN0ijBT4XHSyY_sxrOLz-pphGiKQn0LAgJuqLLT-Q"
}

Create a company

Send a POST request with the following headers and body.

A company will be created if your request is successful. You’ll receive a JSON response similar to the one shown in the example response section.

Headers

POST /auth-v1/companies HTTP/1.1
Host: api-money.sage.com
Content-Type: application/json
Authorization: Bearer {JWT}
X-Application: {app name}

Where:

  • POST /auth-v1/companies is the Authentication Service endpoint where you send your request.
  • api-money.sage.com is your request’s base URL.
  • Bearer {JWT} is the authorization string for your request. {JWT} is the JSON Web Token you obtained in Get an access token for the organisation.
  • {app name} is the name of an app supported by, and in the format accepted by Authentication Service. For example: sage.intacct.

Body

{
  "name": "{company name}",
  "externalId": "{external ID}",
  "taxNumber": "{tax number}",
  "standardIndustrialCode": "{SIC}",
  "contactTelNo": "{phone}",
  "contactEmail": "{email}"
}

Where:

  • {company name} is the name of the company you want to create.

  • {external ID} is the external ID for the company. If you don’t want to assign an external ID, set this value to null.

  • {tax number} is the tax number of the company.

  • {SIC} is the Standard Industrial Classification (SIC) code for the company. For details, see the Division of Corporation Finance: Standard Industrial Classification (SIC) Code List.

  • contactTelNo is the company telephone number.

  • contactEmail is the company email.

Example response

{
  "companyId": "a9ad9268-afe0-4550-b4fb-5d0ba80a58b8",
  "organisationId": "661c3957-8cf0-4eaf-b446-601344674c3c",
  "name": "My company",
  "externalId": "MyCompanyExternalID-12345",
  "logoUrl": "",
  "address": {
    "addressLine1": "",
    "addressLine2": "",
    "addressLine3": "",
    "addressLine4": "",
    "countrySubdivision": "",
    "postalCode": "",
    "country": ""
  },
  "taxNumber": "123456789",
  "standardIndustrialCode": "1799",
  "contactTelNo": "123456789",
  "contactEmail": "[email protected]"
}

Where:

  • companyId contains an automatically generated unique ID of the created company. You can use this ID to retrieve or update the company details via the REST API.

  • organisationId contains the unique ID of the organisation where you created the company. This is the organisation created in Create an organisation.

  • logoUrl contains the URL used to upload or update the company logo. If this parameter is empty, you can create an upload URL yourself.

  • address contains the company address. If this parameter is empty, you can update it with your company’s address.

  • name, externalID, taxNumber, standardIndustrialCode, contactTelNo, and contactEmail – These contain the values you defined in the body of your request.

Get an access token for the company

To work with a company via the Consumer API, you need to obtain an access token and use it to sign your HTTP requests.

The company and organisation’s unique IDs (companyId, organisationId) are used to generate the token. They allow you to work with that company only.

To work with another company you’ll need to obtain a new access token.

Send a GET request with the following headers.

You’ll receive an access token in the JSON response if your request is successful.

Each access token expires after a certain amount of time. To obtain a new access token for the company, send your GET request again.

Headers

GET /auth-v1/accesstoken HTTP/1.1
Host: api-money.sage.com
X-Organisation-Id: {organisation ID}
X-Company-Id: {company ID}
X-Nonce: {unique value}
X-Signature: {signature}
X-Application: {app name}

Where:

  • GET /auth-v1/accesstoken is the Consumer API endpoint where you send your request.
  • api-money.sage.com is your request’s base URL.
  • {organisation ID} is the ID of the organisation that includes the company.
  • {company ID} is the ID of the company you want to generate an access token for.
  • {unique value} is an arbitrary unique value, such as a GUID. In each HTTP request you must use a new value.
  • {signature} is the signature for your request. Read our generating an X-signature guide for more information.
  • {app name} is the name of an app supported by, and in the format accepted by Authentication Service. For example: sage.intacct.

For more information about this REST resource and its parameters, go to the Onboarding and authentication API reference.

Example response

An access token looks like:

{
  "jwt": "AAAAAAAAAAA.wtwwwnifjaoisdfafMC4wLjAiLCJvcmdhbmlzYXRpb25KKKKKKKJZCI6ImFiMWY3OGIyLTM4NGUtNGUyMC1iMzY2LTZmOTBiODc2M2U2ZSIsInNvdXJjZVByb2R1Y3QiOiJzYWdlLmJyYXppbC5vbmUiLCJraWQiOiI3NTdiNTBmZDhmNDYxODAyNTI2MTFiMDY2ODI2NTBiNDYyYmYyYmE4MzNkMzExYYwMDI3IiwiaXAiOiI4MS4xMjguMjMzLjIwMiIsImlzcyI6IndwYi1hdXRoIiwiY2hhbm5lbCI6Im9ubGluZS1jaGFubmVsIiwiZXhwIjoxNTU2MDE1Njc3LCJzZXJ2aWNlSWQiOiJ3cGItYXV0aC1zZXJ2aWNlIiwiaWF0IjoxNTU2MDE0NDc3fQ.afe3qfgewgpkhidaMgo_nmrrWMEeGvq5q2yFElgZ79AnjQ74yyt1WgXKn8gNH90RwdNXStozG2cTsg8PvPvM0lWV0sRZM3yVOJs2FvZp5aSzFuFq6m2xcjwkLxTys3x1Knx3oZkXTYMoEbI3_ZvwSvxV3DK2cNT888gsTXQuwgJstR2Qpud5abcJIY64-oVnshyuJrgO391n7FHCnn1Hm-9eSegLSIl0zJYN0xVYuT21iRxZk0sObZMC12FC0qNh2gdi-kOUMEdzkJ0iEYeDp4b3tFnUSN0ijBT4XHSyY_sxrOLz-pphGiKQn0LAgJuqLLT-Q"
}

If the headers of the response contain X-Rotate-key then the organisation signing key must be rotated to use the key specified in this header.

Keys rotate approximately every 30 minutes, and you must be checking for the presence of this header for us to be able to approve the on-boarding of your application to production.