Miscellaneous
Authentication
Explanation of the different authentication types and how they work
Authentication
All requests to Handcash must include the headers:
app-secret
app-id
For requests that invoke a particular wallet, user, or business wallet, a Signed Payload is required.
Auth Tokens can be obtained in a couple of different ways:
- Generated by the client server in the Wallet-as-a-Service flow.
- Returned in a query parameter in a redirect in the Handcash Connect flow.
- Found in the business wallet “Wallet” section for a business wallet.
Required Headers for Signed Payload
Include the following headers when making authenticated requests:
Header | Description |
---|---|
app-id | Your application’s unique identifier provided by Handcash. |
app-secret | Your application’s secret key provided by Handcash. |
oauth-publickey | The public key of the wallet or user making the request. |
oauth-timestamp | Current timestamp to prevent replay attacks. |
oauth-nonce | Unique random string per request to prevent replay attacks. |
oauth-signature | ECDSA signature of the request, generated using your private key. |
Generating a Signature
To create the oauth-signature
:
- Create the Signature String: Concatenate the HTTP method, endpoint, body, timestamp, and nonce.
- Hash the Signature String: Use SHA-256 to hash the signature string.
- Sign the Hash: Use ECDSA with your private key to sign the hashed string.
- Include the Signature: Add the signature to the
oauth-signature
header.
Code Snippet
Here’s how to generate the oauth-signature
in JavaScript:
const crypto = require('crypto');
function getRequestSignatureString(method, endpoint, body, timestamp, nonce) {
return `${method}\n${endpoint}\n${timestamp}\n${JSON.stringify(body)}${nonce ? `\n${nonce}` : ''}`;
}
function signPayload(method, endpoint, body, timestamp, privateKey, nonce){
const hash = crypto.Hash.sha256(Buffer.from(getRequestSignatureString(method, endpoint, body, timestamp, nonce)));
return crypto.ECDSA.sign(hash, privateKey).toString();
};