HTTP(s) Authentication


The HTTP requests triggered by the HandCash Connect SDK require authentication in order to identify the app and user behind the request.

When users authorize apps to connect to their wallets, apps will receive an authToken in the redirection URL (check user authentication for more details). The Connect SDK will use that authToken key to sign every HTTP request.


What is the authToken?

The authToken represents the private key of the granted permission. This private key has nothing to do with the user wallet or the blockchain. It's just a session key that can be revoked by the user at any time.

Authentication Headers

Every HTTP of the HandCash Connect API should include the following authentication headers:

oauth-publickeyThe public key from the private key (original authToken)"021a8c7d3de4c7976f74a49d3c0b60a2444bca33a5a4ecd58ca4264385832abccd"
oauth-signatureSignature of the request formatted in DER. Check out signatures for more details."304402207984a2f40f5be442007e45c1b5293d707317a5a10b452ab61386ec93bb68726502207f48cd9f48ad0e4bc564c3c023d8329d886cc019e24ee8bbfa48f14c00dfc1cc"
oauth-timestampThe timestamp formatted in ISO 8601"2022-04-30T19:21:32.000Z"
app-secretApp secret from the app accessing the account. Find it in your HandCash Dashboard."6a6895125da623a0f52dbe27dd1092af10f325f6c06ba0e00b2120aeb4517312"


Only on the server-side

Your app secret should never be exposed. Therefore, HandCash Connect should be only integrated on the server-side. Do not integrate it on the client-side.


Requests must contain the signature in the headers. Particularly, a signature of the following properties:

  • HTTP method - POST
  • Request URL: - <>
  • Request body - {param1: "value", param2: 100}or ""if empty
  • Timestamp - 2022-04-30T19:21:32.000Z
  • Nonce - "anyUniqueRandomString"(optional)

All the fields above are put together to create the signature payload as follows:

  • signature_payload = ${http_method}\n${request_url}\n${timestamp}\n${body}\n${nonce}

We use the private key to sign the signature_payload:

  • signature = ECDSA.sign(authToken, signature_payload).


Signature Algorithm

HandCash Connect secp256k1 with the ECDSA algorithm. The same Elliptic Curve algorithm as Bitcoin to sign the requests.