Authentication

Systems which are transmitting data to SPCM must include an API key with each submission in an HTTP header called X-API-Key. There is no pre-registration required to obtain an API key. You can simply generate your own API key and start using it.

The API key must be between 16 and 64 characters in length. To ensure the security of the system, the API key must be generated using a cryptographically security PRNG and contain a minimum of 96 bits (12 bytes) of entropy. The following .NET code shows a simple way of generating such a key:

public static string GenerateAPIKey() {
    var randomBytes = System.Security.Cryptography.RandomNumberGenerator.GetBytes(12);
    return System.Convert.ToBase64String(randomBytes);
}

Alternatively you can generate a key by making an HTTP GET request to the endpoint: https://spcm.gov.gg/api/v1/generate-api-key [Swagger ]

The purpose of API keys

API keys serve three purposes:

• The Revenue Service may take additional manual steps to review submissions from API keys which have not previously been seen in order to check they are valid submissions.
• The Revenue Service may infer that records sent with the same API key and the same Id represent the same employer or employee as in a previous submission for that API key and Id.
• Senders may amend previously-submitted returns by submitting a new version which uses the same API key and Ids.

You should not create a new API key for every return. Instead, your software should store an API key and reuse it when making subsequent returns for the same employer. This allows the Revenue Service to link employers and employees from one return to the next (by using their "id" properties). It also means you can send a replacement return to correct data if necessary.

API key security

The SPCM APIs secured by API keys are 'write-only', which means that API keys cannot generally be used to retrieve data from the SPCM. However, API keys should be treated as secrets shared between the employer (or their agent) and the Revenue Service.

If you need to display an API key to a user, or export it to a file which could be shared by the user (for example for backup and recovery purposes), then it should be made clear to the user that they should be treated securely.

You must not share API keys between unrelated parties or between unrelated systems. If you use separate systems to submit data for different purposes (e.g. one system for Secondary Pensions and another for Economic Statistics) then you should use a different key for each system. An API key should only continue to be used while producing returns from the same system, from the same source data, with the same identifiers. If in doubt, it is best to discard an API key and generate a fresh one.

Example

The example below uses a curl command to upload a test JSON employer return file called 'return.json' using a random API key:

If the return is valid, then SPCM stores it and allocates a sequential number to it, starting from 1 for your first return. The API provides this number as the response body.