Authentification et Contrôle d'Accès

Clé d'API

Envoyez votre clé dans l'en-tête X-Bifrost-Invoke à chaque requête. Il n'y a ni étape de connexion ni jeton à renouveler : la clé est la crédence.

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

L'accès est revérifié à chaque requête. Révoquer la clé, la laisser expirer ou voir l'accès API désactivé sur le compte prend effet dès la requête suivante, sans attendre l'expiration d'un cache.

• En-tête absent : 401 api_key_missing. Clé inconnue, révoquée ou expirée : 401 api_key_invalid.
• Accès API désactivé pour le compte : 403 api_access_denied.
• E-mail du compte non vérifié : 403 email_not_verified. Vérifiez l'e-mail dans le panneau ; la clé fonctionne dès la requête suivante.
• Compte suspendu : les clés sont conservées mais répondent 401 api_key_invalid pendant la suspension, et fonctionnent de nouveau à la réactivation du compte.

Portées

Une portée est l'autorisation d'atteindre un groupe de points de terminaison. À la création d'une clé, vous choisissez les portées qu'elle porte : une clé servant uniquement à lire les soldes ne peut pas créer un retrait, même si elle fuite.

Appeler un endpoint hors des portées de la clé renvoie 403 en indiquant quelles portées conviendraient, pour que la correction soit visible sans deviner. Certains endpoints en acceptent plusieurs, et en détenir une seule suffit :

{
  "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"]
    }
  }
}

Sur les clés portant une portée d'écriture (payout:write, payin:write, wallets:write), il vaut la peine d'ajouter une seconde couche à la portée : une liste blanche d'IP si votre intégration appelle depuis une adresse fixe, ou la signature de la requête sinon. Aucune des deux n'est obligatoire, mais elles existent parce qu'une crédence qui déplace de l'argent mérite mieux qu'un secret statique.

Liste blanche d'IP

La clé peut être restreinte à un ensemble d'adresses sources. Les adresses individuelles et les plages en notation CIDR sont acceptées, en IPv4 comme en IPv6 :

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

Une requête arrive par une seule famille d'adresses à la fois. Si votre infrastructure nous atteint en IPv4 et en IPv6, déclarez les deux, car une entrée d'une famille n'autorise pas l'autre. Les requêtes hors de la liste sont refusées avec 403 ip_not_authorized.

Signature de la Requête (HMAC)

Facultative par clé. La clé d'API seule prouve que l'appelant connaît un secret statique, mais elle ne prouve ni que la requête est récente, ni que le corps est intact, ni que cet appel n'a pas déjà eu lieu. Avec la signature activée, chaque requête porte une preuve valable une seule fois et sur une courte fenêtre.

La chaîne canonique

Construisez ces six champs joints par un unique caractère de saut de ligne, exactement dans cet ordre :

METHOD
PATH
QUERY
TIMESTAMP
NONCE
SHA256_HEX(BODY)

METHOD en majuscules. PATH est le chemin exactement tel qu'il figure dans la ligne de requête, avec la barre initiale et le préfixe /v1 (par exemple /v1/check-payout/f47ac10b-58cc-4372-a567-0e02b2c3d479) : il n'est pas décodé et la barre finale est conservée. QUERY est la query string brute telle qu'envoyée, sans point d'interrogation initial, ni triée ni réencodée, et vide en l'absence de paramètres. Le dernier champ est le SHA-256 hexadécimal des octets exacts du corps envoyé. Pour les requêtes sans corps, hachez la chaîne vide, ce qui donne e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.

Signer une requête

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

Points de vigilance

• Le secret de signature est affiché une seule fois, à la création de la clé. Il n'est jamais renvoyé, conservez-le donc avant de fermer le panneau.
• Le secret est distinct de la clé d'API. Les deux sont nécessaires : la clé vous identifie, la signature prouve la requête.
• Hachez les octets que vous transmettez réellement. Sérialiser le corps deux fois, ou le re-sérialiser après signature, change le condensé et invalide la signature.
• Chaque nonce est accepté une fois par clé. Renvoyer la requête à l'identique renvoie signature_replayed même si tout le reste est correct.
• Le décalage d'horloge est la cause la plus fréquente de signature_timestamp_out_of_range. Gardez vos serveurs sur NTP.