The authentication process can return a number of different errors such as if the required headers are missing or if the signature does not match.

All of these errors will be returned with the HTTP status code of 401.

AUTH_INVALID_HEADER

This error is returned when a value in an included header is not in the expected format. The message field in the error object will give details about the exact issue.

Example

{
  "errors": [
    {
      "code": "AUTH_INVALID_HEADER",
      "message": "The 'Authorization' header is not in the correct format. It must start with 'KSig1-HMAC-SHA256'."
    }
  ]
}

AUTH_INVALID_API_KEY

This error occurs when the provided API Key as provided in the X-API-Key header is not valid or has be revoked.

{
  "errors": [
    {
      "code": "AUTH_INVALID_API_KEY",
      "message": "The provided API key is not valid or has been revoked."
    }
  ]
}

AUTH_INVALID_AUTH_TOKEN

This error occurs when the Auth Token as provided in the X-API-Auth-Token header is not valid.

{
  "errors": [
    {
      "code": "AUTH_INVALID_AUTH_TOKEN",
      "message": "The authentication token is invalid."
    }
  ]
}

AUTH_SIGNATURE_MISMATCH

This error occurs when the signature that is calculated does not match the signature provided. The most common reasons for this mismatch is that the string to sign did not follow the standards exactly or the X-API-Signed-Elements header does not include all the elements being signed. However, other issues could contribute, such as using the wrong Secret Key to sign the string to sign.

{
  "errors": [
    {
      "code": "AUTH_SIGNATURE_MISMATCH",
      "message": "The provided signature does not match the calculated signature."
    }
  ]
}

AUTH_MISSING_HEADER

This error is returned when a required header is missing.

The following headers are always required:

Other headers may be required if X-API-Signed-Elements is included and indicates data elements are included in the signature and those elements are not already required (such as X-API-Key) or included implicitly with the request (such as the HTTP method and URL).

Example

{
  "errors": [
    {
      "code": "AUTH_MISSING_HEADER",
      "message": "Required header 'X-API-Key' is missing from the request."
    }
  ]
}