Authentication

All requests to the external API gateway require authentication headers. These headers validate the request and ensure secure access to your organization’s data.

---

Authentication Architecture & Signature Flow

The diagram below details how incoming requests are authenticated, timestamp/nonce-verified, signature-checked, and checked against IP whitelists.

---

Request Headers

Include the following credentials and metadata in your request headers:

Header	Description	Example
x-client-id	The unique Client ID assigned to your application.	veda_pub_a935d5f172268cdf122572defcc2631b
x-nonce	A unique random string generated fresh for every request to prevent replay attacks.	2346301255735
x-timestamp	The current UTC timestamp in milliseconds when the request is sent.	1696301254321

---

Example GET Request

curl -X GET "https://api.yourdomain.com/api/v1/external/products" \
     -H "x-client-id: veda_pub_a935d5f172268cdf122572defcc2631b" \
     -H "x-nonce: 2346301255735" \
     -H "x-timestamp: 1696301254321"

---

Request Signing (POST / PUT / PATCH)

For all state-changing requests (POST, PUT, PATCH), you must include a cryptographic signature of the JSON payload. This signature ensures payload integrity and authenticity.

How to Generate the Signature

1. Inject Nonce and Timestamp: Before signing, add nonce (a unique random string) and timestamp (current Unix timestamp as an integer in milliseconds) directly into your JSON payload body.
2. Base64 Encode Payload: Convert the complete JSON payload into stringified JSON and encode it into a Base64 string.
3. Compute HMAC-SHA256: Hash the Base64-encoded string using the HMAC-SHA256 algorithm with your Client Secret (e.g., veda_sec_cceac1bd...) as the secret key.
4. Attach Signature: Include the resulting hexadecimal signature string under the signature field inside your JSON payload body.

Example in Node.js

const crypto = require('crypto');

function prepareSignedPayload(payload, clientSecret) {
  // 1. Add unique timestamp and nonce to the body
  payload.timestamp = Date.now();
  payload.nonce = crypto.randomUUID();

  // 2. Base64 encode the payload string
  const jsonString = JSON.stringify(payload);
  const base64Payload = Buffer.from(jsonString).toString('base64');

  // 3. Generate the HMAC-SHA256 signature
  const signature = crypto
    .createHmac('sha256', clientSecret)
    .update(base64Payload)
    .digest('hex');

  // 4. Attach signature to payload
  payload.signature = signature;

  return payload;
}

---

Authentication Error Responses

Below are the exact JSON error responses returned by the gateway when authentication checks fail:

1. Missing or Invalid Client ID (401 Unauthorized)

{
  "success": false,
  "status": 401,
  "message": "Invalid or inactive Client ID or API Key."
}

2. Missing Header (401 Unauthorized)

{
  "success": false,
  "status": 401,
  "message": "Request timestamp (x-timestamp) is missing."
}

3. Expired Timestamp (401 Unauthorized)

{
  "success": false,
  "status": 401,
  "message": "Request timestamp expired or invalid."
}

4. Nonce Replay Attack Detected (401 Unauthorized)

{
  "success": false,
  "status": 401,
  "message": "Replay attack detected: Request nonce already used."
}

5. IP Address Not Whitelisted (403 Forbidden)

{
  "success": false,
  "status": 403,
  "message": "Access denied from IP address: 203.0.113.99"
}