Autenticação da API

Chaves de API

Toda requisição à API é autenticada com uma chave de API que pertence à sua conta. As chaves têm o formato mk_live_ seguido de 32 caracteres e são criadas no painel, em API keys.

Armazenamos apenas um hash SHA-256 de cada chave, então a chave completa é exibida uma única vez, no momento da criação. Se você perder uma chave, crie uma nova e revogue a antiga. Dependendo do seu plano, você pode ter várias chaves ao mesmo tempo. Usar uma por aplicação ou ambiente é um bom hábito.

Três formas de enviar sua chave

Envie a chave da forma que melhor se adapta ao seu cliente HTTP. As três são equivalentes:

# 1. Parâmetro de consulta
curl "https://metalapi.com/api/v1/latest?api_key=YOUR_API_KEY"

# 2. Cabeçalho Authorization (token Bearer)
curl "https://metalapi.com/api/v1/latest" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 3. Cabeçalho X-API-Key
curl "https://metalapi.com/api/v1/latest" \
  -H "X-API-Key: YOUR_API_KEY"

Em produção, prefira um cabeçalho. Removemos a chave da query string antes de gravar nosso log de requisições, mas os seus próprios logs, proxies e ferramentas de rastreamento de erros podem guardar a URL completa.

Uma chave ausente retorna o erro 101, e uma chave desconhecida ou revogada retorna 102, ambos com status HTTP 401.

Chaves restritas por domínio

Chamar a API a partir de JavaScript no lado do cliente expõe a sua chave a todos os visitantes. Se for necessário fazer isso, primeiro restrinja a chave aos seus próprios domínios no painel.

Uma chave restrita só responde a requisições de navegador cujo cabeçalho Origin (ou Referer) corresponda a um dos domínios permitidos ou aos seus subdomínios. Requisições de qualquer outro site são rejeitadas com o erro 107 (HTTP 403) e não são cobradas.

Requisições sem cabeçalho Origin ou Referer, como chamadas de servidor para servidor feitas pelo seu backend, cron jobs ou scripts, são sempre permitidas. Assim, uma única chave restrita pode atender tanto ao seu site quanto ao seu servidor. Com example.com na lista de domínios permitidos:

# Permitida: requisição de navegador a partir de um subdomínio de um domínio permitido
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Origin: https://shop.example.com"

# Rejeitada com 107: a origem não está na lista
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Origin: https://another-site.com"

# Permitida: requisição de servidor para servidor sem Origin nem Referer
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: YOUR_API_KEY"

Mantendo as chaves seguras

• Mantenha as chaves no servidor e carregue-as de variáveis de ambiente ou de um gerenciador de segredos. Nunca faça commit delas no Git.
• Use uma chave separada por aplicação e ambiente, para poder revogar uma sem afetar as outras.
• Se uma chave vazar, crie uma substituta, faça o deploy dela e depois revogue a chave antiga no painel.
• Sempre chame a API via https://.
• Para páginas web públicas, um widget incorporável exibe preços ao vivo sem nenhuma chave na página.

// Somente no servidor: a chave nunca chega ao navegador
const res = await fetch("https://metalapi.com/api/v1/latest?currencies=XAU,XAG", {
  headers: { "X-API-Key": process.env.METALAPI_KEY },
});