Autenticación y Control de Acceso

Clave de API

Envía tu clave en la cabecera X-Bifrost-Invoke en cada solicitud. No hay paso de inicio de sesión ni token que renovar: la clave es la credencial.

curl -X GET "https://bridge.bifrostcrypto.com/v1/balances" \
  -H "X-Bifrost-Invoke: YOUR_API_KEY"

El acceso se vuelve a verificar en cada solicitud. Revocar la clave, dejarla expirar o tener el acceso a la API desactivado en la cuenta surte efecto en la siguiente solicitud, sin esperar a que venza ninguna caché.

• Encabezado ausente: 401 api_key_missing. Clave desconocida, revocada o expirada: 401 api_key_invalid.
• Acceso a la API desactivado en la cuenta: 403 api_access_denied.
• E-mail de la cuenta no verificado: 403 email_not_verified. Verifique el e-mail en el panel; la clave empieza a funcionar en la siguiente solicitud.
• Cuenta suspendida: las claves se conservan, pero responden 401 api_key_invalid mientras dure la suspensión y vuelven a funcionar cuando se reactiva la cuenta.

Alcances

Un alcance es el permiso de llegar a un grupo de endpoints. Al crear una clave eliges qué alcances lleva, de modo que una clave usada solo para leer saldos no pueda crear un retiro aunque se filtre.

Llamar a un endpoint fuera de los ámbitos de la clave devuelve 403 indicando qué ámbitos servirían, para que la corrección sea visible sin adivinar. Algunos endpoints aceptan más de uno, y basta con tener cualquiera:

{
  "error": {
    "code": "scope_denied",
    "message": "This API key does not have permission for this endpoint",
    "details": {
      "required_scopes": ["payout:write"],
      "granted_scopes": ["balances:read", "payin:read"]
    }
  }
}

En las claves con alcance de escritura (payout:write, payin:write, wallets:write) conviene sumar una segunda capa al alcance: lista blanca de IP, si su integración llama desde una dirección fija, o firma de la solicitud, si no lo hace. Ninguna de las dos es obligatoria, pero ambas existen porque una credencial que mueve dinero merece más que un secreto estático.

Lista blanca de IP

La clave puede restringirse a un conjunto de direcciones de origen. Se aceptan direcciones individuales y rangos en notación CIDR, tanto IPv4 como IPv6:

["203.0.113.10", "198.51.100.0/24", "2001:db8::/32"]

Una solicitud llega por una familia de direcciones a la vez. Si su infraestructura nos alcanza por IPv4 y por IPv6, declare ambas, porque una entrada de una familia no autoriza la otra. Las solicitudes de fuera de la lista se rechazan con 403 ip_not_authorized.

Firma de la Solicitud (HMAC)

Opcional por clave. La clave de API por sí sola prueba que quien llamó conoce un secreto estático, pero no prueba que la solicitud sea reciente, que el cuerpo esté íntegro, ni que esa llamada no haya ocurrido ya. Con la firma activada, cada solicitud lleva una prueba válida una sola vez y por una ventana corta.

La cadena canónica

Construye estos seis campos unidos por un único carácter de salto de línea, exactamente en este orden:

METHOD
PATH
QUERY
TIMESTAMP
NONCE
SHA256_HEX(BODY)

METHOD en mayúsculas. PATH es la ruta exactamente como aparece en la línea de la solicitud, con la barra inicial y el prefijo /v1 (por ejemplo /v1/check-payout/f47ac10b-58cc-4372-a567-0e02b2c3d479): no se decodifica y la barra final se conserva. QUERY es la query string cruda tal como se envía, sin el signo de interrogación inicial, sin reordenar ni recodificar, y queda vacía cuando no hay parámetros. El último campo es el SHA-256 en hexadecimal de los bytes exactos del cuerpo que envía. En solicitudes sin cuerpo, use el hash de la cadena vacía, que es e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.

Firmando una solicitud

const crypto = require("crypto");

const secret = process.env.BIFROST_SIGNING_SECRET;
const method = "POST";
const path = "/v1/payout";
const query = "";
const body = JSON.stringify({ /* ... */ });

const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = crypto.randomBytes(16).toString("hex");
const bodyHash = crypto.createHash("sha256").update(body).digest("hex");

const canonical = [method, path, query, timestamp, nonce, bodyHash].join("\n");
const signature = crypto
  .createHmac("sha256", secret)
  .update(canonical)
  .digest("hex");

await fetch("https://bridge.bifrostcrypto.com" + path, {
  method,
  headers: {
    "X-Bifrost-Invoke": process.env.BIFROST_API_KEY,
    "X-Bifrost-Timestamp": timestamp,
    "X-Bifrost-Nonce": nonce,
    "X-Bifrost-Signature": signature,
    "Content-Type": "application/json",
  },
  body,
});

Puntos a tener en cuenta

• El secreto de firma se muestra una sola vez, al crear la clave. Nunca se devuelve de nuevo, así que guárdalo antes de cerrar el panel.
• El secreto es distinto de la clave de API. Ambos son necesarios: la clave te identifica, la firma prueba la solicitud.
• Calcula el hash de los mismos bytes que transmites. Serializar el cuerpo dos veces, o volver a serializarlo tras firmar, cambia el resumen e invalida la firma.
• Cada nonce se acepta una vez por clave. Reenviar la solicitud idéntica devuelve signature_replayed aunque todo lo demás sea correcto.
• El desfase de reloj es la causa más común de signature_timestamp_out_of_range. Mantén tus servidores con NTP.