Authentication

You'll need to authenticate every request to access any of the referral endpoints in the referral-api.wealth.com API. In this guide, we'll look at how authentication works. Wealth.com referral API uses a header and payload signatures value to authenticate your request.

API Key

With API Key authentication, you use your API Key to authenticate your HTTP requests. Here's how to authenticate using cURL:

curl 'https://referral-api.wealth.com/v1/refer/partner-id' \
  -H 'x-api-key: [YOUR API KEY]' \

Please don't commit your Wealth.com API Key to GitHub!

API Key Rotation

Multiple keys can be assigned to every client_id for the purposes of rotating key in your infrastructure. This feature will allow your organization to rotate keys based on your internal policies. When you would like to rotate keys please speak to support and we will add new and remove old keys for you.

Payload Signature

Every request to the Referral API will require partners to digitally sign the payload using their private key of their RSA key pair.

1. Get the current date-timestamp in ISO 8601 format
2. Stringify the payload being sent
3. Format the message to sign as “{isoDatetime}.{jsonStringifiedPayload}”
4. Generate the signature using SHA256, partners private RSA key, and the formatted message
5. Format the signature as “{isoDatetime},{signatureOutputAsHex}”
6. Send the formatted signature as the user-data-signature header value

  const nowIso = new Date().toISOString();
  const keyString = Buffer.from(`${nowIso}.${JSON.stringify(requestPayload)}`);
  const payloadSignature = crypto.sign("SHA256", keyString, privateKey);
  const signature = `${nowIso},${payloadSignature.toString('hex')}`;

Key Rotation

Key rotation is a standard security best practice and Wealth.com understands the needs to comply with these practices. You can schedule a payload signature key rotation with our support staff and exchange the .PEM file to update your digital signature keys.