مصادقة API

مفاتيح API

يُصادَق كل طلب إلى الواجهة بمفتاح API يخص حسابك. تكون المفاتيح على شكل mk_live_ يليها 32 حرفًا، وتُنشأ من لوحة التحكم ضمن API keys.

لا نخزّن إلا قيمة تجزئة SHA-256 لكل مفتاح، لذا يُعرض المفتاح كاملًا مرة واحدة فقط عند إنشائه. إذا فقدت مفتاحًا، فأنشئ مفتاحًا جديدًا وألغِ القديم. وبحسب خطتك يمكنك الاحتفاظ بعدة مفاتيح في الوقت نفسه، ومن العادات الجيدة تخصيص مفتاح لكل تطبيق أو بيئة.

ثلاث طرق لإرسال مفتاحك

مرّر المفتاح بالطريقة التي تناسب عميل HTTP لديك، فالطرق الثلاث متكافئة:

# 1. Query parameter
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"

فضّل الترويسة في بيئة الإنتاج. نحن نحذف المفتاح من سلسلة الاستعلام قبل كتابة سجل الطلبات لدينا، لكن سجلاتك أنت والخوادم الوكيلة وأدوات تتبّع الأخطاء قد تحتفظ بعنوان URL كاملًا.

يؤدي غياب المفتاح إلى الخطأ 101، ويؤدي المفتاح غير المعروف أو الملغى إلى الخطأ 102، وكلاهما مع حالة HTTP 401.

المفاتيح المقيّدة بالنطاق

استدعاء الواجهة من JavaScript في جانب العميل يكشف مفتاحك لكل زائر. إذا كان لا بد من ذلك، فقيّد المفتاح بنطاقاتك من لوحة التحكم أولًا.

لا يستجيب المفتاح المقيّد إلا لطلبات المتصفح التي تطابق ترويسة Origin (أو Referer) فيها أحد النطاقات المسموح بها أو نطاقاتها الفرعية. أما الطلبات الصادرة من أي موقع آخر فتُرفض بالخطأ 107 (HTTP 403) ولا تُحتسب عليك.

الطلبات التي لا تحتوي على ترويسة Origin أو Referer، مثل الاستدعاءات من خادم إلى خادم الصادرة من الواجهة الخلفية لديك أو من المهام المجدولة أو السكربتات، مسموح بها دائمًا. لذلك يمكن لمفتاح مقيّد واحد أن يخدم موقعك وخادمك معًا. مع وجود example.com في قائمة النطاقات المسموح بها:

# Allowed: browser request from a subdomain of an allowed domain
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Origin: https://shop.example.com"

# Rejected with 107: origin is not on the list
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Origin: https://another-site.com"

# Allowed: server-to-server request without Origin or Referer
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: YOUR_API_KEY"

حماية المفاتيح

• احتفظ بالمفاتيح على الخادم وحمّلها من متغيرات البيئة أو من مدير أسرار، ولا ترفعها أبدًا إلى Git.
• استخدم مفتاحًا منفصلًا لكل تطبيق وبيئة، حتى تتمكن من إلغاء أحدها دون المساس بالبقية.
• إذا تسرّب مفتاح، فأنشئ بديلًا وانشره، ثم ألغِ المفتاح القديم من لوحة التحكم.
• استدعِ الواجهة دائمًا عبر https://.
• في صفحات الويب العامة، تعرض ودجة قابلة للتضمين الأسعار اللحظية دون وضع أي مفتاح في الصفحة.

// Server-side only: the key never reaches the browser
const res = await fetch("https://metalapi.com/api/v1/latest?currencies=XAU,XAG", {
  headers: { "X-API-Key": process.env.METALAPI_KEY },
});