Autenticação e Controle de Acesso

Chave de API

Envie sua chave no cabeçalho X-Bifrost-Invoke em toda requisição. Não há etapa de login nem token a renovar: a chave é a credencial.

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

O acesso é reconferido a cada requisição. Revogar a chave, deixá-la expirar ou ter o acesso à API desativado na conta vale já na requisição seguinte, sem esperar cache nenhum vencer.

• Cabeçalho ausente: 401 api_key_missing. Chave desconhecida, revogada ou expirada: 401 api_key_invalid.
• Acesso à API desativado na conta: 403 api_access_denied.
• E-mail da conta não verificado: 403 email_not_verified. Verifique o e-mail no painel; a chave passa a funcionar na requisição seguinte.
• Conta suspensa: as chaves são mantidas, mas respondem 401 api_key_invalid enquanto durar a suspensão, e voltam a funcionar quando a conta é reativada.

Escopos

Escopo é a permissão de alcançar um grupo de endpoints. Ao criar uma chave você escolhe quais escopos ela carrega, de modo que uma chave usada só para ler saldos não consiga criar um saque nem se vazar.

Chamar um endpoint fora dos escopos da chave devolve 403 informando quais escopos serviriam, para que a correção fique visível sem adivinhação. Alguns endpoints aceitam mais de um, e ter qualquer um deles basta:

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

Nas chaves com escopo de escrita (payout:write, payin:write, wallets:write) vale somar uma segunda camada ao escopo: whitelist de IP, se a sua integração chama de endereço fixo, ou assinatura da requisição, se não chama. Nenhuma das duas é obrigatória, e as duas existem porque uma credencial que movimenta dinheiro merece mais que um segredo estático.

Whitelist de IP

A chave pode ser restringida a um conjunto de endereços de origem. São aceitos endereços individuais e faixas em notação CIDR, tanto IPv4 quanto IPv6:

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

Uma requisição chega por uma família de endereços de cada vez. Se sua infraestrutura nos alcança por IPv4 e por IPv6, declare as duas, porque uma entrada de uma família não autoriza a outra. Requisições de fora da lista são recusadas com 403 ip_not_authorized.

Assinatura da Requisição (HMAC)

Opcional por chave. A chave de API sozinha prova que quem chamou conhece um segredo estático, mas não prova que a requisição é recente, que o corpo está íntegro, nem que aquela chamada já não aconteceu. Com assinatura ligada, cada requisição carrega uma prova válida uma única vez e por uma janela curta.

A string canônica

Monte estes seis campos unidos por um único caractere de quebra de linha, exatamente nesta ordem:

METHOD
PATH
QUERY
TIMESTAMP
NONCE
SHA256_HEX(BODY)

METHOD em maiúsculas. PATH é o caminho exatamente como aparece na linha da requisição, com a barra inicial e o prefixo /v1 (por exemplo /v1/check-payout/f47ac10b-58cc-4372-a567-0e02b2c3d479): não é decodificado e a barra final é mantida. QUERY é a query string crua como enviada, sem o ponto de interrogação inicial, sem reordenar e sem recodificar, e fica vazia quando não há parâmetros. O último campo é o SHA-256 em hexadecimal dos bytes exatos do corpo que você envia. Em requisições sem corpo, use o hash da string vazia, que é e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.

Assinando uma requisição

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

Pontos de atenção

• O segredo de assinatura é exibido uma única vez, na criação da chave. Ele nunca mais é devolvido, então guarde antes de fechar o painel.
• O segredo é separado da chave de API. Os dois são necessários: a chave identifica você, a assinatura prova a requisição.
• Faça o hash dos mesmos bytes que você transmite. Serializar o corpo duas vezes, ou reserializar depois de assinar, muda o resumo e invalida a assinatura.
• Cada nonce é aceito uma vez por chave. Reenviar a requisição idêntica devolve signature_replayed mesmo com todo o resto correto.
• Relógio fora de hora é a causa mais comum de signature_timestamp_out_of_range. Mantenha seus servidores em NTP.