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 belowprivateKey

Default RSA public key:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtcCqeDWTR4HFCAXd5lMC
UUfBwhqwP1Bwp/bJinU6WMxdcYivITQBw3D0zwOESm23bYtpI4npiuIPo4p31ir+
sNYvrBkOHRWcFOQKNdMOvm3JvQAUVr4juvoqOTSGvIpmPwee1/GMY6ImL4h78dm5
L6FbFzQbebPdnLSVnLDOmYSl3Ydcc480FWT8ODEuOsJfEnD/LxAPmQ5KxQ9RAhct
7U+QNTya1iCckLyf9HLinokanYyNUW0PEx16g7agfndkKAR8phOTup9tpGlLRObD
OY/JySH/hTaLx4g96uXtdsGWeCqvK+DrqP/L9uexM5WfXXNEepbh0qxPlj+7ur1Y
gwIDAQAB
-----END 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.

-----BEGIN PRIVATE KEY-----
    MIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQC1wKp4NZNHgcUI
    Bd3mUwJRR8HCGrA/UHCn9smKdTpYzF1xiK8hNAHDcPTPA4RKbbdti2kjiemK4g+j
    infWKv6w1i+sGQ4dFZwU5Ao10w6+bcm9ABRWviO6+io5NIa8imY/B57X8YxjoiYv
    iHvx2bkvoVsXNBt5s92ctJWcsM6ZhKXdh1xzjzQVZPw4MS46wl8ScP8vEA+ZDkrF
    D1ECFy3tT5A1PJrWIJyQvJ/0cuKeiRqdjI1RbQ8THXqDtqB+d2QoBHymE5O6n22k
    aUtE5sM5j8nJIf+FNovHiD3q5e12wZZ4Kq8r4Ouo/8v257EzlZ9dc0R6luHSrE+W
    P7u6vViDAgMBAAECggEAfp6n5DEm1sVAV9OGgMRJtAhyouBm8uT+ZvWV+MCsklpl
    qwfXQiFyLQ9Pbbz8d8Gx7T4XVCvrKNdOn9eCnxC6+MVu1s1puLdqUl+AAXl1JxNj
    XSlmAfxa9hL8QXgnechNbRHJBpYAARVg1vKVrqrIybb2t9aUYZf+BwMDy/KdK/NB
    66isdPTtNY9meiGx9kyxzjBdtJx7bR+2Xk5+mOTQT9hNSyAG/6DnVjvhPH/+J5PF
    Di8hElA0e6TgXDf04EX2Ow2fu+I/NR8XvCCBITDmqRsqt8Js4XA9WS7MEK+0Og3g
    jnDDJdYjG9jroEo4WwpdD5FBhlff9JlWsx3p24MSyQKBgQDaXsknPUZHy6MYgq+h
    79R6/AQyIsDF/+lkCIGVY3GC9EF0/Orp3OvsQursBT7LT2Nd2OA73GGdp1YV5rbI
    pKNN1qB5HiB70RNaYi7dGwFBG4JA6OumHFH/Udq4FKjrRTYVD5JPEAMiozvM4jX2
    cQjCF+mIlPcuDtCZ/MU2R1+nfwKBgQDVEoYozNezCxKxL8zIVp8wriOS5GL6qiqS
    p0l2V70GjHoqBpgdZ3DEpq8GwO7aEOd8EDzsBgvki5ozSxiE56Ukb7P87cGn3uGE
    EiKsAsgfZ9kQqs34iyPKoMXJ4vqQ198GO0zEWRDA4CdMv4kdPYT/QwY4fMJNLo7s
    0hEe3LMw/QKBgQC7K1VE4dtUfHG9933s0jEQfORnyKvsyk3UpQnU7tiDgzJ7wLDl
    ZKt+5ViQlmpdPx2Pee2wwVOWGrDJsufmkF88v4LqbW0wU2NALDm44IWxtY9ubXZV
    +Z46toE/GM40Yi1Z3e/s/m+Bh+Ig2Z+hLP9xxacwn2ZCPwaDhknPHVwapwKBgQC/
    T+6d268g16Rk66JXj09IClNupRoqL3giTYosdAMJSkC2U01puWMLbw5gZgMQUXVH
    c9z/nz42axJ9U8QkMUmaOaHGTERBUmHyj8YJ5EWDzV6dFH/z1hrA6TIuX1rTisB5
    e+0lr0LXq2weASw/0OkFuUxwk7RyUIeMI+GzcD6EkQKBgQCEws5i3mVU//S/lLxc
    x9zH5/iNMCWozuFLhPzbausOu9AWzu2V2ic8heDLAowi8s4JE2FFQh4EQFRgsm0T
    ZuR39t4h+uVsjKNIyWmtt+PecmQOzptgha3tLGmadPCjBOgvBnH4UIuBZTGEUx9P
    S/ejPXIT8R2ooqy/qy674jVjlA==
    -----END PRIVATE KEY-----

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:

  1. The partnerId as extracted from the request.
  2. The key used to perform the hashing or signing. Will be either the default or the one passed in via the header.
  3. An object authorizationHeader with the header related data. It contains the raw header and each component of the header as parsed by our service.
  4. 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.
  5. 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
    }
  }
}