Authentication & Access Control

API Key

Send your key in the X-Bifrost-Invoke header on every request. There is no login step and no token to refresh: the key is the credential.

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

Access is re-checked on every request. Revoking a key, letting it expire, or having API access disabled for the account takes effect on the very next request, without waiting for any cache to expire.

• Missing header: 401 api_key_missing. Unknown, revoked or expired key: 401 api_key_invalid.
• API access disabled for the account: 403 api_access_denied.
• Account e-mail not verified: 403 email_not_verified. Verify the e-mail in the panel; the key starts working on the next request.
• Suspended account: the keys are kept but answer 401 api_key_invalid while the suspension lasts, and work again when the account is reactivated.

Scopes

A scope is a permission to reach a group of endpoints. When you create a key you can pick which scopes it carries, so a key used only to read balances cannot create a payout even if it leaks.

Calling an endpoint outside the key's scopes returns 403 stating which scopes would work, so the fix is visible without guesswork. Some endpoints accept more than one, and holding any of them is enough:

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

On keys carrying a write scope (payout:write, payin:write, wallets:write) it is worth adding a second layer on top of the scope: an IP whitelist if your integration calls from a fixed address, or request signing if it does not. Neither is mandatory, but both exist because a credential that moves funds deserves more than a static secret.

IP Whitelist

A key can be restricted to a set of source addresses. Individual addresses and CIDR ranges are both accepted, in IPv4 and IPv6:

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

A request arrives from one address family at a time. If your infrastructure reaches us over both IPv4 and IPv6, declare both, because an entry for one family does not authorize the other. Requests from outside the list are refused with 403 ip_not_authorized.

Request Signature (HMAC)

Optional per key. The API Key alone proves that the caller knows a static secret, but it does not prove the request is recent, that the body is intact, or that the call has not already happened. With signing enabled, each request carries a proof valid once and only for a short window.

The canonical string

Build these six fields joined by a single newline character, in this exact order:

METHOD
PATH
QUERY
TIMESTAMP
NONCE
SHA256_HEX(BODY)

METHOD is uppercase. PATH is the path exactly as it appears in your request line, with its leading slash and the /v1 prefix (for example /v1/check-payout/f47ac10b-58cc-4372-a567-0e02b2c3d479): it is not URL-decoded and a trailing slash is kept. QUERY is the raw query string as sent, with no leading question mark, not sorted and not re-encoded, and is empty when there are no parameters. The last field is the hex SHA-256 of the exact body bytes you send. For requests without a body, hash the empty string, which yields e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.

Signing a request

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

What to keep in mind

• The signing secret is shown once, when the key is created. It is never returned again, so store it before closing the panel.
• The secret is separate from the API Key. Both are needed: the key identifies you, the signature proves the request.
• Hash the same bytes you actually transmit. Serializing the body twice, or reserializing after signing, changes the digest and invalidates the signature.
• Each nonce is accepted once per key. Replaying a request verbatim returns signature_replayed even when everything else is correct.
• Clock drift is the most common cause of signature_timestamp_out_of_range. Keep your servers on NTP.