API Kimlik Doğrulaması

API anahtarları

Her API isteği, hesabınıza ait bir API anahtarıyla doğrulanır. Anahtarlar mk_live_ ve ardından gelen 32 karakterden oluşur ve paneldeki API keys bölümünde oluşturulur.

Her anahtarın yalnızca SHA-256 hash değerini saklarız; bu nedenle tam anahtar yalnızca bir kez, oluşturduğunuz anda gösterilir. Bir anahtarı kaybederseniz yeni bir anahtar oluşturun ve eskisini iptal edin. Planınıza bağlı olarak aynı anda birden fazla anahtarınız olabilir. Her uygulama veya ortam için ayrı bir anahtar kullanmak iyi bir alışkanlıktır.

Anahtarınızı göndermenin üç yolu

Anahtarı, HTTP istemcinize hangisi uygunsa o yolla gönderin. Üç yöntem de eşdeğerdir:

# 1. Sorgu parametresi
curl "https://metalapi.com/api/v1/latest?api_key=YOUR_API_KEY"

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

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

Canlı ortamda header kullanmayı tercih edin. Anahtarı istek loglarımıza yazmadan önce sorgu dizesinden çıkarırız, ancak kendi loglarınız, proxy'leriniz ve hata izleme araçlarınız tam URL'yi saklayabilir.

Anahtar eksikse 101, anahtar bilinmiyor veya iptal edilmişse 102 hatası döner; her ikisi de HTTP 401 durum koduyla gelir.

Alan adıyla sınırlandırılmış anahtarlar

API'yi istemci tarafı JavaScript'ten çağırmak, anahtarınızı her ziyaretçiye açık hale getirir. Bunu yapmak zorundaysanız önce panelden anahtarı kendi alan adlarınızla sınırlandırın.

Sınırlandırılmış bir anahtar, yalnızca Origin (veya Referer) header'ı izin verilen alan adlarından biriyle ya da bunların alt alan adlarıyla eşleşen tarayıcı isteklerine yanıt verir. Başka web sitelerinden gelen istekler 107 hatasıyla (HTTP 403) reddedilir ve ücretlendirilmez.

Backend'inizden yapılan sunucudan sunucuya çağrılar, cron işleri veya betikler gibi Origin ya da Referer header'ı içermeyen isteklere her zaman izin verilir. Böylece tek bir sınırlandırılmış anahtar hem web sitenize hem de sunucunuza hizmet verebilir. İzin listesinde example.com varken:

# İzin verilir: izin verilen bir alan adının alt alan adından gelen tarayıcı isteği
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Origin: https://shop.example.com"

# 107 ile reddedilir: origin listede değil
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Origin: https://another-site.com"

# İzin verilir: Origin veya Referer içermeyen sunucudan sunucuya istek
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: YOUR_API_KEY"

Anahtarları güvende tutmak

• Anahtarları sunucuda tutun ve ortam değişkenlerinden ya da bir gizli bilgi yöneticisinden (secrets manager) yükleyin. Asla Git'e commit etmeyin.
• Her uygulama ve ortam için ayrı bir anahtar kullanın; böylece birini diğerlerine dokunmadan iptal edebilirsiniz.
• Bir anahtar sızarsa yerine yenisini oluşturun, dağıtın ve ardından eski anahtarı panelden iptal edin.
• API'yi her zaman https:// üzerinden çağırın.
• Herkese açık web sayfalarında gömülebilir bir widget, sayfaya hiçbir anahtar koymadan canlı fiyatları gösterir.

// Yalnızca sunucu tarafı: anahtar asla tarayıcıya ulaşmaz
const res = await fetch("https://metalapi.com/api/v1/latest?currencies=XAU,XAG", {
  headers: { "X-API-Key": process.env.METALAPI_KEY },
});