جدول المحتويات

نظرة عامة مصادقة مفتاح API نمط رمز Bearer تنفيذ OAuth 2.0 إدارة رمز JWT استراتيجية تدوير المفاتيح المصادقة متعددة العوامل أفضل ممارسات الأمان أنماط المؤسسات استكشاف الأخطاء وإصلاحها

توثيق API

أنماط المصادقة المتقدمة — OAuth 2.0، JWT، تدوير المفاتيح

أتقن آليات المصادقة المتطورة لدمج Smart Money API في بيئات المؤسسات. تعلم تدفقات OAuth 2.0، أنماط رمز JWT، تدوير المفاتيح الآمن، وتنفيذ المصادقة متعددة العوامل.

نُشر في 21 مارس 2026 • 18 دقيقة قراءة • متقدم

نظرة عامة على المصادقة

يدعم Smart Money API طرقًا متعددة للمصادقة مصممة لاستيعاب هياكل التطبيقات المختلفة، متطلبات الأمان، وسياسات المؤسسات. فهم هذه الأنماط يضمن أن تكاملك آمن وفعال.

تعمل المصادقة في Smart Money API عبر ثلاث طبقات رئيسية:

مفاتيح API — مصادقة رمز Bearer البسيطة للتطوير والتكاملات المباشرة
رموز JWT — رموز موقعة تشفيريًا بدون حالة لأنظمة التوزيع والخدمات الصغيرة
OAuth 2.0 — إطار عمل تفويض للوصول للتكاملات الخارجية وتطبيقات SaaS

مبدأ الأمان: لا تعرض بيانات الاعتماد للمصادقة في كود العميل، السجلات، التحكم في الإصدار، أو رسائل الخطأ. نفذ تدوير بيانات الاعتماد على جدول زمني وفورًا عند الاختراق.

كل طريقة لها مزايا مميزة. تعمل مفاتيح API بشكل أفضل للتواصل بين الخلفيات حيث يتم التحكم في تخزين بيانات الاعتماد. تتفوق رموز JWT في الهياكل الموزعة حيث لا يوجد حالة مشتركة. يوفر OAuth 2.0 وصولًا مفوضًا للمستخدم للتطبيقات الخارجية.

مصادقة مفتاح API

مفاتيح API هي أبسط آلية للمصادقة — فهي سلاسل عشوائية يتم إنشاؤها لحسابك لتحديد تطبيقك لـ Smart Money API. يجب أن تتضمن كل طلب مفتاح API الخاص بك إما كرأس أو كمعلمة استعلام.

مفتاح API بناءً على الرأس

الطريقة الموصى بها هي تمرير مفتاح API الخاص بك في رأس Authorization باستخدام مخطط Bearer:

مثال curl
curl -X GET "https://api.smartmoneyapi.com/v1/whales/btc" \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -H "Accept: application/json"

مفتاح API كمعلمة استعلام

للاتصالات عبر WebSocket أو عندما لا يمكن تعديل الرؤوس، قم بتمرير مفتاح API كمعلمة استعلام:

اتصال WebSocket
ws://localhost:8877/ws?api_key=sk_live_1234567890abcdef
// يُنشئ تدفق WebSocket مصادقًا عليه

خصائص مفتاح API

الخاصية	الوصف
التنسيق	سلسلة سداسية عشرية مكونة من 128 حرفًا تبدأ بـ sk_test_ أو sk_live_
النطاق	يرث جميع الأذونات الخاصة بالحساب الذي أنشأه
الانتهاء	لا تنتهي صلاحيته تلقائيًا؛ يجب تدويره يدويًا
التدوير	قم بإنشاء مفتاح جديد، وهجرة الحركة، ثم إلغاء تنشيط المفتاح القديم
حدود المعدل	مشتركة عبر جميع الطلبات التي تستخدم نفس المفتاح

ممارسات أمان مفتاح API

متغيرات البيئة — قم بتخزين المفاتيح في ملفات .env (غير مضافة إلى التحكم في الإصدار) وتحميلها أثناء التشغيل
أنظمة الخزائن — استخدم HashiCorp Vault أو AWS Secrets Manager أو Azure Key Vault في الإنتاج
مفاتيح منفصلة — حافظ على مفاتيح اختبار ومفاتيح حية منفصلة؛ وقم بتدوير مفاتيح الاختبار بشكل متكرر
النطاق الأدنى — أنشئ مفاتيح منفصلة للتكاملات المختلفة عندما يكون ذلك ممكنًا
تسجيل التدقيق — سجل جميع أحداث إنشاء واستخدام مفاتيح API

احصل على مفتاح API الخاص بك في 30 ثانية

هل أنت مستعد للبناء؟ احصل على مفتاح API مجاني (100 استدعاء/يوم، بدون بطاقة) وابدأ في سحب بيانات الحيتان والتمويل وسلسلة الكتل الحية.

احصل على مفتاح API →

نمط Bearer Token

تمتد Bearer tokens مفهوم مفتاح API البسيط بإضافة السياق وانتهاء الصلاحية وآليات التحديث. وهي مثالية للتطبيقات التي تحتاج إلى إدارة برمجية للاعتمادات.

الحصول على Bearer Tokens

قم بتبادل مفتاح API والسر الخاص بك للحصول على Bearer token صالح لمدة 24 ساعة:

GET /auth/token
curl -X POST "https://api.smartmoneyapi.com/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
 "api_key": "sk_live_1234567890",
 "api_secret": "secret_abcxyz"
  }'

Token Response Format

تعيد النقطة الطرفية Bearer token مع البيانات الوصفية:

Response
{
 "access_token": "eyJhbGciOiJIUzI1NiIs...",
 "token_type": "Bearer",
 "expires_in": 86400,
 "refresh_token": "refresh_1234567..."
}

استخدام Bearer Tokens

قم بتضمين الرمز في رأس Authorization لجميع الطلبات اللاحقة:

Authenticated Request
curl -X GET "https://api.smartmoneyapi.com/v1/derivatives/funding-heatmap" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Token Refresh Flow

عندما يقترب الرمز من انتهاء الصلاحية، استخدم Refresh token للحصول على رمز جديد دون الحاجة إلى السر الخاص بـ API:

POST /auth/refresh
curl -X POST "https://api.smartmoneyapi.com/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{
 "refresh_token": "refresh_1234567..."
  }'

OAuth 2.0 Implementation

يتيح OAuth 2.0 للمستخدمين منح التطبيقات الوصول إلى حسابات Smart Money API الخاصة بهم دون مشاركة الاعتمادات. هذا ضروري لمنصات SaaS والتكاملات الخارجية والتطبيقات متعددة المستأجرين.

OAuth 2.0 Authorization Code Flow

التدفق القياسي لتطبيقات الويب:

User Initiates Login — ينقر المستخدم على "الاتصال بـ Smart Money API"
Redirect to Authorization Server — يقوم تطبيقك بإعادة توجيه المستخدم إلى نقطة نهاية التفويض الخاصة بـ Smart Money
User Grants Permission — يراجع المستخدم النطاقات المطلوبة ويوافق على الوصول
Authorization Code Returned — يتم إعادة توجيه المستخدم مع رمز التفويض
Exchange Code for Token — يقوم الخلفي بتبادل الرمز للحصول على رمز الوصول (لا يتم عرض الرمز أبدًا في الواجهة الأمامية)
Store Token — تخزين رمز التحديث بشكل آمن؛ استخدم رمز الوصول لاستدعاءات API

الخطوة 1: توجيه المستخدم إلى نقطة نهاية التفويض

إعادة التوجيه من الواجهة الأمامية
// عنوان URL لإعادة توجيه المستخدم إليه
const authUrl = new URL('https://api.smartmoneyapi.com/oauth/authorize');
authUrl.searchParams.append('client_id', 'your_client_id');
authUrl.searchParams.append('redirect_uri', 'https://yourapp.com/callback');
authUrl.searchParams.append('response_type', 'code');
authUrl.searchParams.append('scope', 'whales derivatives onchain');
authUrl.searchParams.append('state', generateRandomState());
window.location.href = authUrl.toString();

الخطوة 2: معالجة رد الاتصال وتبادل الرمز

تبادل الرمز من الخلفية
// الخلفية تعالج مسار /callback
const code = req.query.code;
const storedState = req.session.state;
const receivedState = req.query.state;
// التحقق من معلمة state
if (storedState !== receivedState) {
  throw new Error('State mismatch - CSRF attack detected');
}
// تبادل الرمز للحصول على الرمز المميز
const tokenResponse = await fetch('https://api.smartmoneyapi.com/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    code: code,
    client_id: process.env.OAUTH_CLIENT_ID,
    client_secret: process.env.OAUTH_CLIENT_SECRET,
    redirect_uri: 'https://yourapp.com/callback'
  })
});
const tokens = await tokenResponse.json();
// تخزين الرموز المميزة بشكل آمن

نطاقات OAuth

اطلب فقط النطاقات التي يحتاجها تطبيقك. Smart Money API تحدد هذه النطاقات:

النطاق	الوصف
whales	الوصول إلى تتبع محافظ الحيتان ومقاييس التراكم
derivatives	الوصول إلى بيانات العقود الآجلة والدائمة ومعدلات التمويل
onchain	الوصول إلى تدفقات المعاملات على السلسلة والتحليلات
alerts	إنشاء وإدارة تنبيهات الويب هوك
offline	الوصول إلى رموز التحديث للحصول على رموز وصول جديدة دون اتصال

إدارة رمز JWT

توفر JWT (رموز الويب JSON) مصادقة بدون حالة—لا يحتاج الخادم إلى تخزين بيانات الجلسة. يستخدم Smart Money API RS256 (توقيع RSA مع SHA-256) لتوقيع الرموز، مما يسمح بالتحقق دون الاتصال بـ API.

هيكل JWT

تتكون رموز JWT من ثلاثة أجزاء مفصولة بنقاط:

تنسيق JWT
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFjY3QxMjM0In0.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
// HEADER.PAYLOAD.SIGNATURE

رأس JWT

يحدد الرأس الخوارزمية ونوع الرمز:

رأس مفكوك
{
 "alg": "RS256",
 "typ": "JWT",
 "kid": "1"
}

مطالبات حمولة JWT

تحتوي الحمولة على مطالبات (تصريحات حول المستخدم/التطبيق):

حمولة مفكوكة
{
 "sub": "acct_1234567890",
 "name": "Trading Bot",
 "iat": 1703001600,
 "exp": 1703088000,
 "scopes": ["whales", "derivatives"],
 "aud": "https://api.smartmoneyapi.com"
}

التحقق من توقيعات JWT

قم بتنزيل المفتاح العام لـ Smart Money وتحقق من الرموز قبل قبولها:

التحقق باستخدام Node.js
const jwt = require('jsonwebtoken');
const fs = require('fs');
// الحصول على المفتاح العام من Smart Money API
const publicKey = fs.readFileSync('smartmoney-public.pem');
// التحقق من الرمز
try {
  const decoded = jwt.verify(token, publicKey, {
    algorithms: ['RS256'],
    audience: 'https://api.smartmoneyapi.com',
    issuer: 'https://api.smartmoneyapi.com'
  });
  // الرمز صالح، استخدم المطالبات المفكوكة
} catch (err) {
  // الرمز غير صالح أو منتهي الصلاحية
}

استراتيجية تناوب المفاتيح

يعد تناوب المفاتيح المنتظم أمرًا بالغ الأهمية للحفاظ على الأمان. حتى مع أفضل الممارسات الأمنية، افترض أن المفاتيح يمكن اختراقها وقم بتنفيذ التناوب المنهجي.

تكرار التناوب

توصي Smart Money بجداول تناوب مختلفة بناءً على نوع المفتاح والاستخدام:

نوع المفتاح	التناوب الموصى به	الحد الأدنى للتناوب
مفاتيح API الاختبارية	شهريًا	ربع سنوي
مفاتيح API للإنتاج	ربع سنوي	سنويًا
رموز تحديث OAuth	تلقائي (بعد 90 يومًا)	يدوي (بعد 180 يومًا)
مفاتيح حساب الخدمة	نصف سنوي	سنويًا

عملية التناوب دون توقف

قم بتناوب المفاتيح دون مقاطعة الخدمة:

إنشاء مفتاح جديد — إنشاء مفتاح API جديد عبر لوحة التحكم أو API
نشر المفتاح الجديد — تحديث أسرار التطبيق في البيئة الانتقالية، واختبارها بدقة
النشر التدريجي — نشر على 10٪ من الخوادم، ومراقبة الأخطاء
النشر الكامل — نشر على الخوادم المتبقية
التحقق من حركة المرور — تأكيد استخدام جميع الطلبات للمفتاح الجديد
تعطيل المفتاح القديم — وضع علامة على المفتاح القديم على أنه غير نشط ولكن لا تحذفه على الفور
حذف المفتاح القديم — بعد 48 ساعة دون أخطاء، حذف نهائيًا

تناوب المفاتيح الطارئ

إذا كنت تشك في اختراق أحد المفاتيح:

تناوب طارئ
// إجراء فوري: تعطيل المفتاح المخترق
curl -X POST "https://api.smartmoneyapi.com/v1/keys/sk_live_xxx/revoke" \
  -H "Authorization: Bearer token"
// إنشاء مفتاح بديل على الفور
curl -X POST "https://api.smartmoneyapi.com/v1/keys" \
  -H "Content-Type: application/json" \
  -d '{
 "name": "مفتاح بديل طارئ"
  }'

التناوب التلقائي في Kubernetes

استخدم Kubernetes Secrets والمشغلات للتناوب التلقائي:

CronJob لتناوب المفاتيح
apiVersion: batch/v1
kind: CronJob
metadata:
  name: api-key-rotator
spec:
  schedule: "0 0 * * 0"  # أسبوعيًا يوم الأحد
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: rotator
            image: smartmoney-key-rotator:latest

المصادقة متعددة العوامل (MFA)

بالنسبة للحسابات التي تصل إلى بيانات الإنتاج، توفر MFA طبقة أمان إضافية من خلال طلب عامل ثاني بخلاف بيانات الاعتماد فقط.

طرق MFA المدعومة

TOTP (كلمة مرور لمرة واحدة قائمة على الوقت) — تطبيقات مثل Google Authenticator، Authy
WebAuthn/FIDO2 — مفاتيح أمان الأجهزة، القياسات الحيوية
رموز SMS لمرة واحدة — أقل أمانًا ولكن مدعومة عالميًا
تأكيد البريد الإلكتروني — رموز تأكيد تُرسل إلى البريد الإلكتروني المسجل

تمكين TOTP للوصول إلى الحساب

تمكين MFA
// الخطوة 1: طلب إعداد MFA
curl -X POST "https://api.smartmoneyapi.com/v1/account/mfa/enable" \
  -H "Authorization: Bearer token"
// الرد يتضمن عنوان URL لرمز QR
{
 "qr_code_url": "https://...",
 "secret": "JBSWY3DPEBLW64TMMQ...",
 "backup_codes": ["12345678", ...]
}

MFA أثناء عمليات API

قد تتطلب بعض العمليات تأكيد MFA حتى بعد المصادقة:

تحدي MFA
// محاولة إجراء عملية حساسة (تناوب المفتاح)
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
  -H "Authorization: Bearer token" \
  -H "X-MFA-Token: mfa_challenge_abc123"
// الرد: MFA مطلوبة
{
 "error": "mfa_required",
 "mfa_token": "mfa_xyz789"
}
// إعادة المحاولة باستخدام رمز TOTP
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
  -H "Authorization: Bearer token" \
  -H "X-MFA-Code: 123456"

أفضل ممارسات الأمان

المصادقة تكون قوية بقوة تنفيذها. اتبع هذه الممارسات للحفاظ على الأمان:

إدارة الأسرار

لا تقم أبدًا بإدخال الأسرار في نظام التحكم في الإصدار — استخدم ملفات .env مع .gitignore
استخدم متغيرات البيئة — تحميل من أنظمة إدارة الأسرار الآمنة
فحص المستودعات — استخدم أدوات مثل TruffleHog، detect-secrets للعثور على المفاتيح المكشوفة
مراجعة سجلات الوصول — مراقبة من قام بالوصول إلى الأسرار ومتى

أمان النقل

استخدم HTTPS دائمًا — لا ترسل بيانات الاعتماد عبر اتصالات غير مشفرة
تحقق من شهادات SSL — لا تعطيل التحقق من الشهادات في بيئة الإنتاج
استخدم تثبيت الشهادة — بالنسبة للتطبيقات المحمولة، منع هجمات MITM
فرض TLS 1.2+ — تعطيل البروتوكولات الأقدم

معالجة بيانات الاعتماد

تجزئة الأسرار — تخزين تجزئات bcrypt أو Argon2، وليس نصًا عاديًا
تقليل العمر الافتراضي — احتفظ ببيانات الاعتماد في الذاكرة فقط طالما كانت هناك حاجة إليها
مسح البيانات الحساسة — الكتابة فوق بيانات الاعتماد بشكل صريح بعد الاستخدام
استخدم المكتبات الآمنة — لا تقم بتنفيذ التشفير بنفسك

التسجيل والمراقبة

لا تقم بتسجيل بيانات الاعتماد أبدًا — حذف المفاتيح في السجلات، استخدم إخفاء السجلات
تسجيل أحداث المصادقة — تتبع محاولات تسجيل الدخول الناجحة والفاشلة
مراقبة الشذوذ — تنبيه على أنماط الوصول غير العادية
مراجعة استخدام المفاتيح — تتبع المفاتيح التي وصلت إلى أي بيانات

أنماط المصادقة المؤسسية

غالبًا ما تتطلب المؤسسات الكبيرة ضوابط أمان إضافية وقدرات امتثال.

تكامل SAML 2.0

بالنسبة للعملاء المؤسسيين، يدعم Smart Money API تكامل SAML 2.0 مع موفر هوية مؤسستك (Okta، Azure AD، إلخ):

الدخول الموحد (SSO) — يقوم المستخدمون بالمصادقة من خلال IdP الخاص بشركتك
التوفير التلقائي — إنشاء/تعطيل الحسابات بناءً على عضوية المجموعة
التنفيذ — اشتراط SAML لجميع وصول المستخدم

القائمة البيضاء لـ IP

تقييد وصول API إلى عناوين IP أو نطاقات CIDR محددة:

إدارة القائمة البيضاء لعناوين IP
// إضافة عنوان IP إلى القائمة البيضاء
curl -X POST "https://api.smartmoneyapi.com/v1/account/ip-whitelist" \
  -H "Authorization: Bearer token" \
  -d '{
 "cidr": "203.0.113.0/24",
 "description": "خوادم الإنتاج"
  }'

تسجيل التدقيق والامتثال

تتضمن الخطط المؤسسية سجلات تدقيق شاملة للامتثال:

الحدث	البيانات المسجلة
المصادقة	المستخدم، الطابع الزمني، النجاح/الفشل، IP، حالة MFA
عمليات المفاتيح	معرّف المفتاح، الإجراء، المُبادر، الطابع الزمني
تغييرات الحساب	ما الذي تغير، من قام بتغييره، الطابع الزمني، القيم قبل/بعد
وصول البيانات	المستخدم، النقطة النهائية، النطاقات، الطابع الزمني، عدد السجلات

استكشاف أخطاء المصادقة وإصلاحها

خطأ مفتاح API غير صالح

المشكلة: تلقي "401 غير مصرح - مفتاح API غير صالح"

الحلول:

تحقق من تنسيق المفتاح (يجب أن يبدأ بـ sk_test_ أو sk_live_)
تحقق من وجود مسافات زائدة في بداية أو نهاية المفتاح
تأكد من أن المفتاح لم يتم إلغاء تنشيطه أو تدويره
تحقق من أنك تستخدم البيئة الصحيحة (مفتاح اختبار للاختبار، مفتاح حي للإنتاج)
تحقق من أن صلاحيات مفتاح API تتوافق مع متطلبات النقطة النهائية

خطأ انتهاء صلاحية الرمز المميز

المشكلة: انتهت صلاحية الرمز المميز، الطلبات تفشل

الحلول:

استخدم رمز التحديث للحصول على رمز وصول جديد
قم بتنفيذ تحديث الرمز المميز تلقائيًا قبل 5 دقائق من انتهاء الصلاحية
قم بتخزين رمز التحديث بشكل آمن (ليس في localStorage لتطبيقات SPA)
تعامل مع استجابات 401 عن طريق محاولة تدفق رمز التحديث

أخطاء CORS/Preflight

المشكلة: المتصفح يحظر الطلبات مع خطأ CORS

الحلول:

يجب أن تأتي طلبات API من المتصفح من أصول مدرجة في القائمة البيضاء
أضف نطاقك عبر لوحة التحكم: الإعدادات → أصول CORS
يرسل المتصفح طلب OPTIONS preflight تلقائيًا
للتطوير، استخدم localhost:3000 أو ما شابه

عدم اكتمال تحدي MFA

المشكلة: تفشل العمليات التي تتطلب MFA حتى مع استخدام الرمز الصحيح

الحلول:

تأكد من تزامن ساعة الخادم (يعتمد TOTP على الوقت)
الرمز صالح فقط لمدة 30 ثانية، قم بإنشاء رمز جديد
استخدم الرموز الاحتياطية إذا كان تطبيق المصادقة غير متاح
استعادة الحساب متاحة عبر البريد الإلكتروني المسجل

نفذ المصادقة الآمنة اليوم

يدعم Smart Money API المصادقة على مستوى المؤسسات مع OAuth 2.0، JWT، MFA، وتكامل SAML. قم بتأمين تكامل API مع أفضل الممارسات الصناعية.

عرض الخطط المؤسسية

هل تحتاج إلى SAML، القائمة البيضاء لعناوين IP، أو دعم مخصص؟ اتصل بفريق المبيعات لدينا.

أنماط المصادقة المتقدمة — OAuth 2.0، JWT، تدوير المفاتيح

نظرة عامة على المصادقة

مصادقة مفتاح API

مفتاح API بناءً على الرأس

مفتاح API كمعلمة استعلام

خصائص مفتاح API

ممارسات أمان مفتاح API

نمط Bearer Token

الحصول على Bearer Tokens

Token Response Format

استخدام Bearer Tokens

Token Refresh Flow

OAuth 2.0 Implementation

OAuth 2.0 Authorization Code Flow

الخطوة 1: توجيه المستخدم إلى نقطة نهاية التفويض

الخطوة 2: معالجة رد الاتصال وتبادل الرمز

نطاقات OAuth

إدارة رمز JWT

هيكل JWT

رأس JWT

مطالبات حمولة JWT

التحقق من توقيعات JWT

استراتيجية تناوب المفاتيح

تكرار التناوب

عملية التناوب دون توقف

تناوب المفاتيح الطارئ

التناوب التلقائي في Kubernetes

المصادقة متعددة العوامل (MFA)

طرق MFA المدعومة

تمكين TOTP للوصول إلى الحساب

MFA أثناء عمليات API

أفضل ممارسات الأمان

إدارة الأسرار

أمان النقل

معالجة بيانات الاعتماد

التسجيل والمراقبة

أنماط المصادقة المؤسسية

تكامل SAML 2.0

القائمة البيضاء لـ IP

تسجيل التدقيق والامتثال

استكشاف أخطاء المصادقة وإصلاحها

خطأ مفتاح API غير صالح

خطأ انتهاء صلاحية الرمز المميز

أخطاء CORS/Preflight

عدم اكتمال تحدي MFA

نفذ المصادقة الآمنة اليوم

الموارد ذات الصلة

دليل المصادقة →

أفضل ممارسات الأمان →

مرجع رموز الأخطاء →