API Key Authorization

Overview

To ensure the integrity of server requests, every request must be signed. The signature serves as a unique representation of the request and is included in the Authorization header.

Signature Details

The signature is generated using a specific algorithm applied to the request parameters. The resulting value is a canonicalized signing string, ensuring the request's authenticity.

Required Headers

Each client request must include the following headers:

Date

Current time given as a date string in RFC7231 format. Note that this value is always in the GMT timezone.

Example:

Date: Tue, 07 Jun 2014 20:51:35 GMT

Authorization

This header contains information on how the request is authorized:

• algorithm: Defines the signature hashing algorithm, by default hmac-sha256
• headers: Defines the headers used to derive the signature, set this to date
• apikey: The API key used for the request
• signature: The Base64-encoded value of the signing string. See Request Signature.

Example Authorization header:

algorithm="hmac-sha256", headers="date", signature="_base64_here_", apikey="_company_api_key_here_"

Ensure that the Date header value is set to current time. The server allows timestamps that are up to 15 minutes old.

Errors

All returned errors have an HTTP status code of 400 or higher, and a response body as follows:

{
  status: number,
  code: string,
  message: string
}

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": { "type": "number" },
    "code": { "type": "string" },
    "message": { "type": "string" }
  },
  "required": [
    "status",
    "code",
    "message"
  ],
  "additionalProperties": false
}

The following list of errors related to Authorization are common for all License API endpoints:

date_header_diff (400)

authorization_invalid_headers (400)

hmac_required (400)

signature_mismatch (400)

authorization_missing_params (400)

invalid_api_key (400)

revoked_api_key (400)

read_only_api_key (400)