Аутентификация в API

Ключи API

Каждый запрос к API аутентифицируется ключом API, привязанным к вашему аккаунту. Ключи имеют вид mk_live_ и 32 символа после него и создаются в личном кабинете в разделе API keys.

Мы храним только хеш SHA-256 каждого ключа, поэтому полный ключ показывается один раз — при создании. Если вы потеряли ключ, создайте новый и отзовите старый. В зависимости от тарифа у вас может быть несколько ключей одновременно. Хорошая практика — использовать отдельный ключ для каждого приложения или окружения.

Три способа передать ключ

Передавайте ключ тем способом, который удобнее для вашего HTTP-клиента. Все три способа равнозначны:

# 1. Параметр запроса
curl "https://metalapi.com/api/v1/latest?api_key=YOUR_API_KEY"

# 2. Заголовок Authorization (Bearer-токен)
curl "https://metalapi.com/api/v1/latest" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 3. Заголовок X-API-Key
curl "https://metalapi.com/api/v1/latest" \
  -H "X-API-Key: YOUR_API_KEY"

В продакшене лучше передавать ключ в заголовке. Мы удаляем ключ из строки запроса перед записью в наш журнал запросов, но ваши собственные логи, прокси и системы отслеживания ошибок могут сохранять полный URL.

Если ключ не передан, возвращается ошибка 101, а если ключ неизвестен или отозван — 102; в обоих случаях с HTTP-статусом 401.

Ключи с ограничением по доменам

При вызове API из клиентского JavaScript ваш ключ виден каждому посетителю. Если без этого не обойтись, сначала ограничьте ключ доменами вашего сайта в личном кабинете.

Ограниченный ключ отвечает только на те запросы из браузера, у которых заголовок Origin (или Referer) совпадает с одним из разрешённых доменов или их поддоменов. Запросы с любых других сайтов отклоняются с ошибкой 107 (HTTP 403) и не тарифицируются.

Запросы без заголовка Origin или Referer — например, вызовы с вашего бэкенда на сервер, cron-задачи или скрипты — разрешены всегда. Поэтому один ограниченный ключ может обслуживать и ваш сайт, и ваш сервер. Если в списке разрешённых указан example.com:

# Разрешено: запрос из браузера с поддомена разрешённого домена
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Origin: https://shop.example.com"

# Отклонено с ошибкой 107: источника нет в списке
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Origin: https://another-site.com"

# Разрешено: запрос между серверами без Origin и Referer
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: YOUR_API_KEY"

Безопасное хранение ключей

• Храните ключи на сервере и загружайте их из переменных окружения или менеджера секретов. Никогда не добавляйте их в Git.
• Используйте отдельный ключ для каждого приложения и окружения, чтобы можно было отозвать один, не затрагивая остальные.
• Если ключ утёк, создайте новый, разверните его, а затем отзовите старый ключ в личном кабинете.
• Всегда обращайтесь к API по https://.
• Для публичных веб-страниц подойдёт встраиваемый виджет: он показывает актуальные цены без ключа на странице.

// Только на сервере: ключ никогда не попадает в браузер
const res = await fetch("https://metalapi.com/api/v1/latest?currencies=XAU,XAG", {
  headers: { "X-API-Key": process.env.METALAPI_KEY },
});