Authentication Debug Endpoint

In order to provide a secure environment, all auth failures result in the exact same error response. This prevents bad actors from using that information to compromise an account. That means it does not matter if the header is malformed, a property is missing, the response value is invalid, the timestamp is out of date or the nonce was sent twice, the error message will be {"success":false,"errMessage":"Authentication required.","errCode":1003}.

To make debugging easier, we provide an authdebug endpoint (/api/v1/authdebug) which outputs information relating to the incoming authentication header and the server validation of the header. This endpoint consumes an HTTP POST and outputs a JSON object that outlines the steps involved in generating a valid auth header for the request.

📘
Note
For security reasons the Authentication Authentication Debug Endpoint is only available in our certification environment.

Auth Debug Keys

The authdebug endpoint is designed for development purposes, therefore it does not retrieve keys from the database. Instead it uses a set of default keys for all requests. However, we do allow you to override the default keys by specifying custom headers. The following table outlines the default key values for each type and the header name that you can use to override the key value.

Type	Default value	Override header
Digest key	secret	key
HMAC key	secret	key
RSA public key	see below	publicKey
RSA private key	see below	privateKey

Default RSA public key:

To test your auth headers with the RSA method you need to sign your requests with the following RSA private key; it is a match with the default RSA public key listed above. If you override the default public key value with a header parameter, you also have to override the private key as well otherwise the signature steps will not be valid.

The following is a sample /api/authdebug Request with a HMAC header. It overrides the default key by using the key custom header.

curl "https://secure-cert.decryptx.com/api/authdebug" \
        -X POST  \
        --header 'Content-Type: application/json'  \
        --header 'authorization: Hmac username="WATERFORD", nonce="1l5daa1ju1b7lmljc5p4nev0ve", timestamp="1489574949", response="7fd904ec88c5dc9217e178bc8e115b950c243197b5116e3e1fc43061eeb846ac"' \
        --header 'key: ef1ad938150fb15a1384b883a104ce70' \
        -d '{"partnerId":"WATERFORD","partnerKey": "ef1ad938150fb15a1384b883a104ce70", "devicePayload": "02C400C037001C0A8692;6011********3331=2212:***?*15=090210=2CB56EC5E025C2F3C2C67FCF2D0C4C39BB19E60EF31192675E5F1DB6A90070E3000000000000000000000000000000000000000035343154313132373038629949960E001D20004A029603", "clientId": "my_client", "reference": "723f57e1-e9c8-48cb-81d9-547ad2b76435s"}'

The /api/authdebug endpoint responds with a JSON object that has the following data:

The partnerId as extracted from the request.
The key used to perform the hashing or signing. Will be either the default or the one passed in via the header.
An object authorizationHeader with the header related data. It contains the raw header and each component of the header as parsed by our service.
An object called signatureSteps containing data for each of the auth steps involved in generating the response hash/signature. It extracts the relevant information from the incoming request and combines them with the nonce and timestamp from the auth header to generate the response.
An object result that details the validity of the incoming auth header. It has a section dedicated to the response property of the auth header and another for the timestamp. They both have an isValid property that outlines whether the incoming request has a valid response (header value matches the service generated value) and valid timestamp (header timestamp is less than 15 minutes old).

Output

{
  "partnerId": "WATERFORD",
  "key": "ef1ad938150fb15a1384b883a104ce70",
  "authorizationHeader": {
    "raw"       : "Hmac username=\"WATERFORD\", nonce=\"1l5daa1ju1b7lmljc5p4nev0ve\", timestamp=\"1489574949\", response=\"7fd904ec88c5dc9217e178bc8e115b950c243197b5116e3e1fc43061eeb846ac\"",
    "method"    : "HMAC",
    "username"  : "WATERFORD",
    "nonce"     : "1l5daa1ju1b7lmljc5p4nev0ve",
    "timestamp" : 1489574949,
    "response"  : "7fd904ec88c5dc9217e178bc8e115b950c243197b5116e3e1fc43061eeb846ac"
  },
  "signatureSteps": {
    "httpVerb"              : "POST",
    "canonicalizedResource" : "/api/authdebug",
    "nonce"                 : "1l5daa1ju1b7lmljc5p4nev0ve",
    "timestamp"             : 1489574949,
    "content"               : "{\"partnerId\":\"WATERFORD\", \"partnerKey\": \"ef1ad938150fb15a1384b883a104ce70\", \"devicePayload\": \"02C400C037001C0A8692;6011********3331=2212:***?*15=090210=2CB56EC5E025C2F3C2C67FCF2D0C4C39BB19E60EF31192675E5F1DB6A90070E3000000000000000000000000000000000000000035343154313132373038629949960E001D20004A029603\", \"clientId\": \"my_client\", \"reference\": \"723f57e1-e9c8-48cb-81d9-547ad2b76435s\"}",
    "contentHash"           : "b6125a0500ade17b6129dac0462cfe3cbaf6866a314d6c98eac19aeac0911b6c",
    "stringToSign"          : "POST /api/authdebug\n1l5daa1ju1b7lmljc5p4nev0ve\n1489574949\n\nb6125a0500ade17b6129dac0462cfe3cbaf6866a314d6c98eac19aeac0911b6c",
    "response"              : "6e37bda316001a670dc0bc3ccfb937bfa120b6ed32f1a12d6e737cf3efb1216e",
    "authHeader"            : "Hmac username=\"WATERFORD\", nonce=\"1l5daa1ju1b7lmljc5p4nev0ve\", timestamp=1489574949,  response=\"6e37bda316001a670dc0bc3ccfb937bfa120b6ed32f1a12d6e737cf3efb1216e\""
  },
  "result": {
    "response": {
      "isValid"  : false,
      "incoming" : "7fd904ec88c5dc9217e178bc8e115b950c243197b5116e3e1fc43061eeb846ac",
      "ours"     : "6e37bda316001a670dc0bc3ccfb937bfa120b6ed32f1a12d6e737cf3efb1216e"
    },
    "timestamp": {
      "isValid"  : false,
      "incoming" : 1489574949,
      "ours"     : 1490613239,
      "offset"   : 1038290
    }
  }
}

📘Note

Auth Debug Keys

Output

📘
Note