Authentication

You'll need to authenticate your requests to access any of the endpoints in the Fystack API. In this guide, we'll look at how authentication works. Fystack uses HMAC-based authentication to securely verify the authenticity of your API requests.

HMAC Authentication

Fystack API uses a secure HMAC-based authentication system that requires you to sign your requests with your API secret. Each request needs three authentication headers:

ACCESS-API-KEY: your_api_key
ACCESS-TIMESTAMP: current_unix_timestamp
ACCESS-SIGN: base64_encoded_hmac_signature

The HMAC signature is generated by combining the HTTP method, request path, timestamp, and request body (if applicable), then signing it with your API secret.

Example Request with Authentication Headers

Here's an example of how to make an authenticated request to the Fystack API:

curl https://api.fystack.io/api/v1/wallets \
-H "ACCESS-API-KEY: your_api_key" \
-H "ACCESS-TIMESTAMP: 1667836889" \
-H "ACCESS-SIGN: YourBase64EncodedSignature=="

Computing the ACCESS-SIGN

To compute the HMAC signature, you'll need to:

1. Create a canonical string from request parameters in fixed order: method, path, timestamp, body
2. Sign this string with your API secret using HMAC-SHA256
3. Hex-encode the HMAC digest, then base64-encode the hex string

Always keep your API secret safe and reset it if you suspect it has been compromised. Here's how to compute the signature in each language:

import CryptoJS from 'crypto-js'

function computeSignature(
  apiSecret: string,
  method: string,
  path: string,
  timestamp: string,
  body: string = ''
): string {
  // Build canonical string in exact order
  const canonical = `method=${method}&path=${path}&timestamp=${timestamp}&body=${body}`

  // HMAC-SHA256 -> hex -> base64
  const hexDigest = CryptoJS.HmacSHA256(canonical, apiSecret)
    .toString(CryptoJS.enc.Hex)

  return btoa(hexDigest)
}

// Example usage
const timestamp = Math.floor(Date.now() / 1000).toString()
const signature = computeSignature(
  'your_api_secret', 'GET',
  '/api/v1/workspaces/your_workspace_id/wallets',
  timestamp
)

const headers = {
  'ACCESS-API-KEY': 'your_api_key',
  'ACCESS-TIMESTAMP': timestamp,
  'ACCESS-SIGN': signature
}

Request signing process

1. Build the canonical string in fixed order: method={METHOD}&path={PATH}&timestamp={TIMESTAMP}&body={BODY}

   • method: HTTP method in uppercase (GET, POST, etc.)
   • path: Request path (e.g. /api/v1/workspaces/{id}/wallets)
   • timestamp: UNIX timestamp in seconds
   • body: JSON-stringified request body, or empty string for GET requests

2. Create the HMAC-SHA256 signature:

   • Sign the canonical string with your API secret
   • Hex-encode the digest
   • Base64-encode the hex string

3. Add required headers:

   • ACCESS-API-KEY: Your API key
   • ACCESS-TIMESTAMP: The timestamp used in the signature
   • ACCESS-SIGN: The base64-encoded signature

Building the Body String

body in the canonical string must be the exact bytes you transmit, for both HMAC and Ed25519. For a GET request, or any request with no body, that's an empty string, never "{}" or null.

The mistake to avoid: serializing the payload twice, once to sign, once when your HTTP client sends it. If what you signed doesn't byte-for-byte match what the server received, ValidateAccessSign fails, even though the payload is logically the same JSON. Serialize once, then reuse that exact string both to build the canonical string and as the literal request body, don't hand your HTTP client the original object/dict/map and trust a second, independent serialization call to reproduce it exactly. Depending on the language this either fails loudly (some HTTP clients reject or mishandle a non-string body outright) or fails silently as a hard-to-debug signature mismatch (if the two serialization calls happen to diverge, from a library upgrade, a different default option, or unusual values like NaN), so don't rely on either outcome, just don't serialize twice.

const payload = { name: 'my-integration' }
const body = JSON.stringify(payload) // serialize once

// sign() uses `body` in the canonical string, exactly as below
const signature = computeSignature(apiSecret, 'POST', path, timestamp, body)

await fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', /* ...auth headers */ },
  // `fetch` requires body to already be a string (or Blob/ArrayBuffer/etc),
  // it will not JSON-serialize `payload` for you, pass `body`, not `payload`
  body
})

Ed25519 Signing

If your API key uses a client key pair instead of an HMAC secret, sign the same canonical string with your Ed25519 private key instead of computing an HMAC. Two differences from the HMAC flow:

• Sign the canonical string bytes directly, there's no separate hashing step, Ed25519 does that internally.
• Base64-encode the raw 64-byte signature straight away, there's no hex step.

ACCESS-SIGN = base64( Ed25519_Sign(privateKey, canonical_string) )

If you're using @fystack/sdk, pass a signer (LocalPrivateKeySigner or AwsKmsSigner) on credentials and it does this for you, see API Keys. The examples below are for signing without the SDK, in other languages.

const crypto = require('crypto');

function computeSignature(privateKeyPem, method, path, timestamp, body = '') {
  const canonical = `method=${method}&path=${path}&timestamp=${timestamp}&body=${body}`;

  const privateKey = crypto.createPrivateKey(privateKeyPem);
  // No digest algorithm, Ed25519 signs the message directly
  const signature = crypto.sign(null, Buffer.from(canonical), privateKey);

  return signature.toString('base64');
}

// Usage
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = computeSignature(
  process.env.PRIVATE_KEY_PEM, 'GET',
  '/api/v1/workspaces/your_workspace_id/wallets',
  timestamp
);

Signing via AWS KMS (non-SDK)

If you're using @fystack/sdk on Node.js, AwsKmsSigner already does this for you, see Client Key Pair. For every other backend, or if you just want to see the mechanism, the same approach works with any language's AWS SDK: call KMS Sign with MessageType: RAW and SigningAlgorithm: ED25519_SHA_512 over the raw canonical string, then base64-encode the returned signature bytes. This is exactly what AwsKmsSigner does internally, the Node.js example below is that same logic written out directly.

import { KMSClient, SignCommand } from '@aws-sdk/client-kms'

async function computeSignature(kmsClient, keyId, method, path, timestamp, body = '') {
  const canonical = `method=${method}&path=${path}&timestamp=${timestamp}&body=${body}`

  const response = await kmsClient.send(new SignCommand({
    KeyId: keyId,
    Message: Buffer.from(canonical, 'utf8'),
    MessageType: 'RAW',
    SigningAlgorithm: 'ED25519_SHA_512'
  }))

  return Buffer.from(response.Signature).toString('base64')
}

kmsClient/client/$kms above is whatever KMS client your language's AWS SDK already gives you, configured however you normally configure it. See Client Key Pair for the general local-vs-production pattern (point it at LocalStack/ministack with static test credentials locally, drop both in production and let the IAM role supply credentials), the same idea applies regardless of language, just through that SDK's own config options.