Autenticación de la API

Claves API

Cada solicitud a la API se autentica con una clave API que pertenece a tu cuenta. Las claves tienen el formato mk_live_ seguido de 32 caracteres y se crean en el panel, en API keys.

Solo almacenamos un hash SHA-256 de cada clave, así que la clave completa se muestra una sola vez, al crearla. Si pierdes una clave, crea una nueva y revoca la anterior. Según tu plan, puedes tener varias claves a la vez. Usar una por aplicación o entorno es un buen hábito.

Tres formas de enviar tu clave

Pasa la clave de la forma que mejor se adapte a tu cliente HTTP. Las tres son equivalentes:

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

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

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

En producción, es preferible usar una cabecera. Eliminamos la clave de la cadena de consulta antes de escribir nuestro registro de solicitudes, pero tus propios logs, proxies y herramientas de seguimiento de errores pueden conservar la URL completa.

Si falta la clave se devuelve el error 101, y una clave desconocida o revocada devuelve 102, ambos con el código de estado HTTP 401.

Claves restringidas por dominio

Llamar a la API desde JavaScript en el cliente expone tu clave a todos los visitantes. Si tienes que hacerlo, primero restringe la clave a tus propios dominios en el panel.

Una clave restringida solo responde a las solicitudes del navegador cuya cabecera Origin (o Referer) coincide con uno de los dominios permitidos o con sus subdominios. Las solicitudes desde cualquier otro sitio web se rechazan con el error 107 (HTTP 403) y no se facturan.

Las solicitudes sin cabecera Origin ni Referer, como las llamadas de servidor a servidor desde tu backend, tareas cron o scripts, siempre se permiten. Por eso, una misma clave restringida puede servir tanto a tu sitio web como a tu servidor. Con example.com en la lista de dominios permitidos:

# Permitida: solicitud del navegador desde un subdominio de un dominio permitido
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Origin: https://shop.example.com"

# Rechazada con 107: el origen no está en la lista
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Origin: https://another-site.com"

# Permitida: solicitud de servidor a servidor sin Origin ni Referer
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: YOUR_API_KEY"

Mantén tus claves seguras

• Mantén las claves en el servidor y cárgalas desde variables de entorno o un gestor de secretos. Nunca las subas a Git.
• Usa una clave distinta por aplicación y entorno, para poder revocar una sin afectar a las demás.
• Si una clave se filtra, crea una de reemplazo, despliégala y después revoca la clave antigua en el panel.
• Llama siempre a la API mediante https://.
• En páginas web públicas, un widget integrable muestra precios en tiempo real sin ninguna clave en la página.

// Solo en el servidor: la clave nunca llega al navegador
const res = await fetch("https://metalapi.com/api/v1/latest?currencies=XAU,XAG", {
  headers: { "X-API-Key": process.env.METALAPI_KEY },
});