HTTP(s) Authentication

Overview

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:

❗

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.

Signatures

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

• HTTP method - POST
• Request URL: - <https://cloud.handcash.io/v1/connect/wallet/pay>
• 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.