Authentication

All HTTP requests must be authenticated using the credentials found in your Developer Dashboard.

For our V4 API services, customers have the flexibility to choose between two different methods for authentication:

API Key

The API Key method provides a straightforward and easy-to-use option, where users simply include their unique API Key in the request headers.

API Signature

the API Signature method offers an additional layer of security by requiring users to generate a signature using their API secret key. This signature is then included in the request headers, ensuring that the requests are authenticated and protected against tampering. Both methods ensure secure access to our API services, allowing customers to select the option that best meets their security and convenience needs.

The signature calculation should be inserted into the custom HTTP header Aply-Signature with Aply-API-Key and Aply-Date.

Header	Information
Aply-API-Key	Your API key as found in your developer portal
Aply-Date	The time you generated the request in ISO-8601 format
Aply-Signature	Calculated signature from request body

NOTE

Every HTTP request should be sent from your server side. If an HTTP request is sent directly from a known web browser (XHR request) with your credentials, we will automatically consider your credentials to be at risk and regenerate your API keys and secret.

Refer to the diagram below for more information.

We use Hash-based Message Authentication Code (HMAC) with the SHA256 digest algorithm to calculate signatures. When creating your HMAC object, use your API secret as the key and digest the date, followed by the request body if one is being sent. An invalid signature will result in your request being rejected.

The Aply-Date should be in ISO-8601 format and is required for us to mitigate potential replay attacks. It also allow to generate a different signature when requesting endpoints that don't have a body like GET requests.

Note that we will sign our response using the same principle. It is up to your implementation to decide whether or not to verify the response integrity using the signature provided.

Please see below for an example of signature calculation:

// app.js

const {
  createHmac,
} = require('node:crypto')
const axios = require('axios').default

const secret = 'YOUR_API_SECRET'
const key = 'YOUR_API_KEY'

function generateSignature(secret, date, data) {
  const hmac = createHmac('sha256', secret)

  hmac.update(date)

  if (data !== null) {
    hmac.update(typeof data === 'string' ? data : JSON.stringify(data))
  }

  return hmac.digest().toString('base64')
}

const http = axios.create({
  baseURL: 'https://integration.aplyid.co.uk',
  headers: {
    'Aply-API-Key': key,
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },

  transformRequest: (data, headers) => {
    const date = new Date().toISOString()

    headers['Aply-Date'] = date
    headers['Aply-Signature'] = generateSignature(secret, date, data)
    return JSON.stringify(data)
  }
})

const payload = { message: "Hello World" }

http.post('/api/v4/ping', payload).then(response => {
  const date = response.headers['aply-date']
  const calculatedSignature = generateSignature(secret, date, response.data)

  if (calculatedSignature === response.headers['aply-signature']) {
    console.log("Signature valid!")
    console.log(response.data)
  } else {
    console.log("Invalid signature from APLYiD")
    throw new Error("Signature from APLYiD doesn't match calculation")
  }
}).catch(error => {
  console.log(error.message)
})

Use the code above, replacing the API key and secret, to see the output as shown below to test your signature.

node signature.js
Signature valid!
{ message: 'Welcome to APLYiD v4 API!' }

Rolling over your API credentials

You now have the possibility to rollover your API credentials in the developer portal.

Under your API key and Secret you will find a Rollover credentials action. This action will generate new credentials and cache for an hour your previous credentials to allow you to update your server side implementation without downtime.

After an hour, your previous credentials will be invalidated and you will need to use the new ones.

You can also use the Regenerate credentials action to invalidate your current credentials plus any cached credentials and generate new ones. This action should only be used in case of a security breach or if you suspect your credentials have been compromised.