Authentication

Authenticate requests with API key authentication using x_starks_api_key and generate the payout signature with the same secret key.

Before you start

• Generate a Client Secret Key in your Starks dashboard under Developers → API Keys.
• Set your client secret as an environment variable: export STARKS_CLIENT_SECRET="your-client-secret".
• Choose the base URL for the environment you are using.

1. Send the standard headers

All requests in the current docs use JSON. Send these headers with each request:

• x_starks_api_key: <your-secret-key>
• Content-Type: application/json

Use a read-only endpoint such as Get list of banks to confirm that your key works before you build a longer integration flow.

export BASE_URL="https://api.starksdevelop.com/"

curl --request GET "${BASE_URL}v1/pay/banks/all" \
  --header "x_starks_api_key: ${STARKS_CLIENT_SECRET}" \
  --header "Content-Type: application/json"

Expected result:

• Success: 200 OK with a JSON response from the API.
• Authentication error: verify that the secret key is valid and the x_starks_api_key header is present.

2. Generate the payout signature when required

The Initialize payout endpoint states that it requires an HMAC SHA512 signature of the request body signed with the same secret key you send in x_starks_api_key.

Sign the exact serialized JSON body you send in the request. If the request body changes after signing, the signature check will fail.

import crypto from "crypto";

const secret = process.env.STARKS_CLIENT_SECRET;
const payload = {
  amount: 80.0,
  currency: "NGN",
  beneficiaryId: "9647f876-c25e-4f6b-a4c5-050211169046",
  narration: "Payment for invoice 101",
};

const body = JSON.stringify(payload);

// Sign the exact request body so the API can verify it has not changed.
const signature = crypto
  .createHmac("sha512", secret)
  .update(body)
  .digest("hex");

console.log({
  body,
  signature,
  headers: {
    x_starks_api_key: secret,
    "Content-Type": "application/json",
    x_starks_signature: signature,
  },
});

{
  "body": "{\"amount\":80,\"currency\":\"NGN\",\"beneficiaryId\":\"9647f876-c25e-4f6b-a4c5-050211169046\",\"narration\":\"Payment for invoice 101\"}",
  "signature": "<hex-signature>",
  "headers": {
    "x_starks_api_key": "your-client-secret",
    "Content-Type": "application/json",
    "x_starks_signature": "<hex-signature>"
  }
}

Optional: Troubleshoot authentication failures

• 401 or 403: verify that your secret key is valid and that you are sending it in the x_starks_api_key header.
• Signature mismatch on payout initialization: sign the exact JSON string you send, not a reformatted version of the payload.
• Request works in one environment but not the other: verify that your key and base URL belong to the same environment.