Skip to content
Developerhome
Product homepage
Payments Out Service

Generate X-Signature

  Less than to read

You need to complete 2 steps to generate an X-Signature. This only relates to cloud applications.

The 2 steps are:

  • Prepare a base string
  • Compute HMAC-SHA1

Prepare a base string

The string must have the following format:

{HTTP METHOD}&{endpoint URL}&{JSON body and path parameters}&{X-Nonce}

Where:

  • {HTTP METHOD} is the HTTP method used in the request for which you generate X-Signature. The HTTP method name must be all uppercase.

Example:

POST
  • {endpoint URL} is the endpoint URL used in the request, percent-encoded.

Example:

https%3A%2F%2Fapi-money.sage.com%2Fauth-v1%2Forganisations

  • {JSON body and path parameters} is the JSON body and path parameters used in your request prepared as described in How to prepare JSON body and path parameters.

  • {X-Nonce} is the value you use in the X-Nonce header of your request. This is an arbitrary unique value such as a GUID, percent-encoded.

Example:

3464fad052e54c41b73546bcf3341f6f

Your base string must always include 3 ampersands (&) even if your request doesn’t have path parameters and body.

Compute HMAC-SHA1

Compute a Hash-based Message Authentication Code using the SHA1 hash function (HMAC-SHA1).

Use the HMAC-SHA1 output value as X-Signature.

  • As an input message, use the base string you prepared.
  • As a secret key, use the initial signing key provided by Sage for your cloud application, with &null appended.

Example:

8B2A4BF8F38CE2424C9AAA1648F4767S3455823DF2654EAC503DE6646EBB3453&null

Examples

How to prepare JSON body and path parameters

We’ll use the following request as an example.

POST https://api-money.sage.com/auth-v1/endpoint?zparameter=123456789&aparameter=AUS

{
    "primaryCountry": "CAN"
}

If your request doesn’t have JSON body or path parameters, leave them out of the following instructions.

To prepare the JSON body and path parameters for use in the base string, do the following:

  1. Encode JSON body in Base64: 
    ewogICAgInByaW1hcnlDb3VudHJ5IjogIkNBTiIKfQ==
  2. Split the body and path parameters into key-value pairs and sort them in the ascending order based on key names: 
    aparameter=123456789
body=ewogICAgInByaW1hcnlDb3VudHJ5IjogIkNBTiIKfQ==
zparameter=AUS
  3. Join the sorted key-value pairs using an ampersand (&): 
    aparameter=123456789&body=ewogICAgInByaW1hcnlDb3VudHJ5IjogIkNBTiIKfQ==&zparameter=AUS
  4. Percent-encode the string: 
    aparameter%3D123456789%26body%3DewogICAgInByaW1hcnlDb3VudHJ5IjogIkNBTiIKfQ%3D%3D%26zparameter%3DAUS
  5. Use this value in the base string instead of the {JSON body and path parameters} placeholder.

JSON body in Base64, converted to key-value pair, and percent-encoded

Source JSON body:

{
    "name" : "My organisation",
    "sageCRMId" : "5f943b4a-657e-4611-a2e8-90c354fc979c",
    "primaryCountry" : "CAN",
    "adminEmail" : "[email protected]",
    "defaultLanguage" : "FR"
}

Same body encoded in Base64, converted to key-value pair, and percent-encoded:

body%3DewogICAgIm5hbWUiIDogIk15IG9yZ2FuaXNhdGlvbiIsCiAgICAic2FnZUNSTUlkIiA6ICI1Zjk0M2I0YS02NTdlLTQ2MTEtYTJlOC05MGMzNTRmYzk3OWMiLAogICAgInByaW1hcnlDb3VudHJ5IiA6ICJDQU4iLAogICAgImFkbWluRW1haWwiIDogImFkbWluaXN0cmF0b3JAbXlkb21haW4uY29tIiwKICAgICJkZWZhdWx0TGFuZ3VhZ2UiIDogIkZSIgp9

Base string

String for a POST request:

POST&https%3A%2F%2Fapi-money.sage.com%2Fauth-v1%2Forganisations&body%3DewogICAgIm5hbWUiIDogIk15IG9yZ2FuaXNhdGlvbiIsCiAgICAic2FnZUNSTUlkIiA6ICI1Zjk0M2I0YS02NTdlLTQ2MTEtYTJlOC05MGMzNTRmYzk3OWMiLAogICAgInByaW1hcnlDb3VudHJ5IiA6ICJDQU4iLAogICAgImFkbWluRW1haWwiIDogImFkbWluaXN0cmF0b3JAbXlkb21haW4uY29tIiwKICAgICJkZWZhdWx0TGFuZ3VhZ2UiIDogIkZSIgp9&3464fad052e54c41b73546bcf3341f6f

String for a GET request without path parameters:

GET&https%3A%2F%2Fapi-money.sage.com%2Fauth-v1%2Forganisations&&3464fad052e54c41b73546bcf3341f6f

JavaScript that generates X-Signature

To generate X-Signature you can use the following code:

var hash = CryptoJS.HmacSHA1(baseString, signingKey + '&null');
var signature = CryptoJS.enc.Base64.stringify(hash);

Where:

  • baseString is the base string prepared as described in Prepare a base string.

  • signingKey is the initial signing key provided by Sage for your cloud application.

X-Signature (HMAC-SHA1 output)

BExDy5OkI6nM/GM8w4FaTWWiosM=