Autenticación

Necesitarás autenticar tus solicitudes para acceder a cualquiera de los endpoints de la API de Fystack. En esta guía veremos cómo funciona la autenticación. Fystack usa autenticación basada en HMAC para verificar de forma segura la autenticidad de tus solicitudes a la API.

Autenticación HMAC

La API de Fystack usa un sistema de autenticación seguro basado en HMAC que requiere que firmes tus solicitudes con tu API secret. Cada solicitud necesita tres headers de autenticación:

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

La firma HMAC se genera combinando el método HTTP, la ruta de la solicitud, el timestamp y el cuerpo de la solicitud (si corresponde), y luego firmando el resultado con tu API secret.

Ejemplo de solicitud con headers de autenticación

Este es un ejemplo de cómo hacer una solicitud autenticada a la API de Fystack:

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

Calcular el ACCESS-SIGN

Para calcular la firma HMAC, debes:

1. Crear un string canónico a partir de los parámetros de la solicitud en un orden fijo: method, path, timestamp, body
2. Firmar este string con tu API secret usando HMAC-SHA256
3. Codificar en hexadecimal el digest HMAC y luego codificar en base64 el string hexadecimal

Mantén siempre seguro tu API secret y restablécelo si sospechas que se ha visto comprometido. Así se calcula la firma en cada lenguaje:

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
}

Proceso de firma de solicitudes

1. Construye el string canónico en un orden fijo: method={METHOD}&path={PATH}&timestamp={TIMESTAMP}&body={BODY}

   • method: método HTTP en mayúsculas (GET, POST, etc.)
   • path: ruta de la solicitud (por ejemplo, /api/v1/workspaces/{id}/wallets)
   • timestamp: timestamp UNIX en segundos
   • body: cuerpo de la solicitud serializado como JSON, o un string vacío para las solicitudes GET

2. Crea la firma HMAC-SHA256:

   • Firma el string canónico con tu API secret
   • Codifica el digest en hexadecimal
   • Codifica en base64 el string hexadecimal

3. Agrega los headers requeridos:

   • ACCESS-API-KEY: tu API key
   • ACCESS-TIMESTAMP: el timestamp usado en la firma
   • ACCESS-SIGN: la firma codificada en base64

Construir el string del cuerpo

body en el string canónico debe ser exactamente los mismos bytes que transmites, tanto para HMAC como para Ed25519. Para una solicitud GET, o cualquier solicitud sin cuerpo, es un string vacío, nunca "{}" ni null.

El error que debes evitar: serializar el payload dos veces, una para firmar y otra cuando tu cliente HTTP lo envía. Si lo que firmaste no coincide byte a byte con lo que recibió el servidor, ValidateAccessSign falla, aunque el payload sea lógicamente el mismo JSON. Serializa una sola vez y luego reutiliza exactamente ese string tanto para construir el string canónico como para el cuerpo literal de la solicitud; no le pases a tu cliente HTTP el objeto/dict/map original confiando en que una segunda serialización independiente lo reproduzca exactamente. Según el lenguaje, esto falla de forma visible (algunos clientes HTTP rechazan o manejan mal un cuerpo que no es string) o falla de forma silenciosa como una discrepancia de firma difícil de depurar (si las dos serializaciones llegan a diferir, por una actualización de biblioteca, una opción predeterminada distinta o valores inusuales como NaN), así que no dependas de ninguno de los dos resultados: simplemente no serialices dos veces.

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
})

Firma con Ed25519

Si tu API key usa un par de claves de cliente en lugar de un secret HMAC, firma el mismo string canónico con tu clave privada Ed25519 en lugar de calcular un HMAC. Hay dos diferencias respecto del flujo HMAC:

• Firma directamente los bytes del string canónico; no hay un paso de hashing separado, Ed25519 lo hace internamente.
• Codifica en base64 directamente la firma raw de 64 bytes; no hay paso hexadecimal.

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

Si usas @fystack/sdk, pasa un signer (LocalPrivateKeySigner o AwsKmsSigner) en credentials y el SDK lo hará por ti; consulta API Keys. Los ejemplos siguientes son para firmar sin el SDK, en otros lenguajes.

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
);

Firma mediante AWS KMS (sin SDK)

Si usas @fystack/sdk en Node.js, AwsKmsSigner ya lo hace por ti; consulta Client Key Pair. Para cualquier otro backend, o si solo quieres ver el mecanismo, el mismo enfoque funciona con el AWS SDK de cualquier lenguaje: llama a Sign de KMS con MessageType: RAW y SigningAlgorithm: ED25519_SHA_512 sobre el string canónico sin procesar y luego codifica en base64 los bytes de la firma devuelta. Esto es exactamente lo que AwsKmsSigner hace internamente; el ejemplo de Node.js a continuación es esa misma lógica escrita de forma directa.

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 en los ejemplos anteriores es el cliente KMS que ya te proporciona el AWS SDK de tu lenguaje, configurado como lo haces normalmente. Consulta Client Key Pair para ver el patrón general de entorno local frente a producción (en local, apúntalo a LocalStack/ministack con credenciales de prueba estáticas; en producción, elimina ambas cosas y deja que el rol de IAM proporcione las credenciales); la misma idea se aplica en cualquier lenguaje, solo que mediante las opciones de configuración de ese SDK.