مفتاح API مقابل JWT وOAuth2: اختر المصادقة المناسبة لواجهة برمجة التطبيقات (API) الخاصة بك

أنت تقوم ببناء واجهة برمجة التطبيقات (API). تعمل نقاط النهاية. تتدفق البيانات. الآن أنت بحاجة للإجابة على واحد سؤال قبل الشحن: كيف يمكن للمتصلين إثبات هويتهم؟

هناك ثلاثة أساليب تهيمن على مصادقة API: مفاتيح API، وJWTs، وOAuth2. يحل كل من أ مشكلة مختلفة. اختر الخيار الخطأ، وسوف تقوم إما بالإفراط في هندسة التكامل البسيط أو ترك ثغرة أمنية في واحدة معقدة.

يقارن هذا الدليل الثلاثة عبر سبعة معايير، مع أمثلة رمز العمل، والقرار الجدول، وتوصيات واضحة بناءً على حالة استخدام واجهة برمجة التطبيقات (API) الخاصة بك.

مصادقة مفتاح API: النهج المباشر

مفتاح API عبارة عن سلسلة عشوائية طويلة تحدد هوية المتصل وتأذن له. يرسل العميل مع كل طلب، يبحث الخادم عنه، وإذا كان يطابق مفتاحًا صالحًا، يتم الطلب يمر.

إليك ما يبدو عليه استدعاء مفتاح واجهة برمجة التطبيقات (API) مع واجهة برمجة تطبيقات botoi:

# API key in a custom header
curl -s -X POST https://api.botoi.com/v1/dns/lookup \\
  -H "Content-Type: application/json" \\
  -H "x-api-key: your_api_key_here" \\
  -d '{"domain": "example.com", "type": "A"}'

إجابة:

{
  "success": true,
  "data": {
    "domain": "example.com",
    "type": "A",
    "records": [
      { "type": "A", "value": "93.184.216.34", "ttl": 86400 }
    ]
  }
}

ال x-api-key الرأس يحمل بيانات الاعتماد. لا توجد رموز للتفاوض، ولا عمليات إعادة توجيه، لا توجد خوادم الترخيص. رأس واحد، بحث واحد، رد واحد.

عندما تفوز مفاتيح API

• مكالمات خادم إلى خادم. تستدعي الواجهة الخلفية الخاصة بك واجهة خلفية أخرى. لا يوجد مستخدم المعنية. تستعلم وظيفة cron عن واجهة برمجة تطبيقات تحديد الموقع الجغرافي لـ IP. يقوم خط أنابيب CI بإجراء فحوصات DNS. المتصل هو دائمًا خادم موثوق به.
• واجهات برمجة التطبيقات المساعدة. واجهات برمجة التطبيقات (APIs) التي تنفذ عمليات عديمة الحالة (التجزئة، والتشفير، التحقق من الصحة، وعمليات البحث) حيث يكون كل طلب مستقلاً. يستخدم botoi مفاتيح API لهذا السبب: أكثر من 150 نقطة نهاية، جميعها عديمة الحالة، وجميعها من خادم إلى خادم.
• التكامل السريع. يقوم المطور بنسخ المفتاح وإضافة رأس واحد ويبدأ الاتصال. لا توجد رقصة OAuth، ولا منطق تحديث الرمز المميز، ولا توجد نقطة نهاية JWKS لتكوينها.

إليك نفس المكالمة في Node.js:

const response = await fetch("https://api.botoi.com/v1/hash", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.BOTOI_API_KEY,
  },
  body: JSON.stringify({ text: "hello world", algorithm: "sha256" }),
});

const result = await response.json();
// result.data.hash = "b94d27b9934d3e08..."

حيث تكون مفاتيح API قصيرة

• لا يوجد هوية المستخدم. يحدد مفتاح API الحساب، وليس المستخدم. إذا ثلاثة مطورين يتشاركون مفتاحًا واحدًا، ولا يمكنك معرفة من قدم أي طلب.
• يتطلب الإلغاء رحلة ذهابًا وإيابًا. إلغاء المفتاح يعني تحديث الخادم مخزن المفاتيح. حتى يتم تحديث ذاكرة التخزين المؤقت، سيظل المفتاح القديم يعمل.
• لا يوجد وصول مفوض. لا يمكنك منح تطبيق تابع لجهة خارجية محدودًا ومؤقتًا الوصول إلى موارد المستخدم باستخدام مفتاح API وحده.

مصادقة JWT: جلسات مستخدم عديمة الحالة

رمز ويب JSON (JWT) هو كائن JSON موقّع يحمل مطالبات بشأن المتصل. المصادقة يقوم الخادم بإنشائه عند تسجيل الدخول؛ يرسلها العميل مع كل طلب؛ خادم الموارد يتحقق من التوقيع دون الاتصال بخادم المصادقة مرة أخرى.

// Header
{
  "alg": "RS256",
  "typ": "JWT"
}

// Payload
{
  "sub": "user_12345",
  "email": "dev@example.com",
  "role": "admin",
  "iat": 1775000000,
  "exp": 1775000900   // 15 minutes
}

// Signature
RSASHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  privateKey
)

يتحقق الخادم من التوقيع باستخدام المفتاح العام. إذا تم التحقق من التوقيع و exp لم يتم اجتياز الطلب، تمت الموافقة على الطلب. لا حاجة للبحث في قاعدة البيانات.

عندما يفوز JWTs

• واجهات برمجة التطبيقات التي تواجه المستخدم مع حركة مرور عالية. يرسل تطبيق الهاتف المحمول JWT على كل طلب. تتحقق بوابة API من التوقيع محليًا بدلاً من الاستعلام عن مخزن الجلسة في كل مكالمة. عند وصول 10000 طلب في الثانية، فإن اتصال قاعدة البيانات هذا الذي تخطيته مهم.
• بنيات الخدمات المصغرة. الخدمة "أ" تستدعي الخدمة "ب" باستخدام JWT. الخدمة ب يتحقق من صحته محليًا ويستخرج معرف المستخدم وأدواره من المطالبات. لا توجد جلسة مشتركة قاعدة البيانات بين الخدمات.
• إذن قصير الأجل. رمز مدته 15 دقيقة لتحميل الملف. 5 دقائق رمز لتأكيد الدفع. يتم خبز انتهاء الصلاحية في الرمز المميز نفسه.

إليك البرنامج الوسيط Express الذي يتحقق من JWT:

import jwt from "jsonwebtoken";

function authMiddleware(req, res, next) {
  const token = req.headers.authorization?.replace("Bearer ", "");
  if (!token) return res.status(401).json({ error: "Missing token" });

  try {
    const decoded = jwt.verify(token, process.env.JWT_PUBLIC_KEY, {
      algorithms: ["RS256"],
    });
    req.user = decoded;
    next();
  } catch (err) {
    return res.status(401).json({ error: "Invalid or expired token" });
  }
}

حيث تقصر JWTs

• من الصعب إلغاء الرمز المميز. JWT صالح حتى تنتهي صلاحيته. إذا قام المستخدم بتسجيل الدخول أو كنت بحاجة إلى إلغاء الوصول، فأنت بحاجة إلى قائمة حظر من جانب الخادم، والتي تعيد مكالمة قاعدة البيانات التي كنت تحاول تجنبها.
• حجم الحمولة. تضيف كل مطالبة بايتات. JWT مع أدوار المستخدم، والأذونات، ويمكن أن تصل البيانات الوصفية إلى 1-2 كيلو بايت. هذا يعني 1-2 كيلوبايت لكل طلب، في كل رأس.
• تعقيد دوران المفتاح. عند تدوير مفاتيح التوقيع، يتم توقيع الرموز المميزة القديمة مع المفتاح السابق يجب أن يظل صالحًا حتى تنتهي صلاحيته. وهذا يعني خدمة متعددة المفاتيح العامة عبر نقطة نهاية JWKS والتعامل مع ملف kid مطالبة الرأس.

OAuth2: الوصول المفوض لأطراف ثالثة

OAuth2 هو إطار عمل ترخيص، وليس بروتوكول مصادقة. يتيح للمستخدم منح أ تطبيق طرف ثالث يحد من الوصول إلى مواردهم على خدمة أخرى، دون مشاركة كلمة المرور الخاصة بهم.

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

# Step 1: Redirect user to authorization server
GET https://auth.example.com/authorize?
  response_type=code&
  client_id=your_app_id&
  redirect_uri=https://yourapp.com/callback&
  scope=read:repos+write:issues&
  state=random_csrf_token

# Step 2: Exchange authorization code for tokens
POST https://auth.example.com/token
  grant_type=authorization_code&
  code=AUTH_CODE_FROM_CALLBACK&
  client_id=your_app_id&
  client_secret=your_app_secret&
  redirect_uri=https://yourapp.com/callback

# Step 3: Call the API with the access token
curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \\
  https://api.example.com/v1/repos

عندما يفوز OAuth2

• تكاملات الطرف الثالث. أنت تدير منصة وتريد مطورين خارجيين لإنشاء تطبيقات يمكنها الوصول إلى بيانات المستخدمين. يمنح OAuth2 المستخدمين التحكم في كل تطبيق يمكن الوصول إليها.
• نطاقات دقيقة الحبيبات. read:repos ولكن لا delete:repos. write:issues ولكن لا admin:org. OAuth2 تتيح النطاقات للمستخدمين الموافقة على أذونات محددة.
• يتدفق "تسجيل الدخول باستخدام X". عندما يستخدم تطبيقك Google أو GitHub أو Microsoft لـ تسجيل الدخول، فأنت تستخدم OAuth2 (غالبًا مع OpenID Connect في الأعلى) للحصول على رمز الهوية.

حيث يقصر OAuth2

• تعقيد. يحتوي OAuth2 على أربعة أنواع من المنح، ورموز التحديث، والتفويض الخوادم، وإعادة توجيه URIs، وPKCE، ونقاط النهاية لاستبطان الرمز المميز. للحصول على واجهة برمجة التطبيقات (API) المساعدة مع لا يوجد سياق للمستخدم، وهذا هو الحمل دون أي فائدة.
• احتكاك التكامل. المطور الذي يريد الاتصال بنقطة نهاية التجزئة الخاصة بك لا يريد تسجيل تطبيق OAuth، وإعداد عناوين URI لإعادة التوجيه، وتفويض التبادل رموز. إنهم يريدون مفتاحًا وأمر تجعيد.
• عبء إدارة الرمز المميز. تنتهي صلاحية رموز الوصول. تحديث الرموز المميزة تدور. يحتاج العملاء إلى منطق إعادة المحاولة للاستجابات 401. بالنسبة للمكالمات البسيطة من خادم إلى خادم، هذا هو الآلات غير الضرورية.

جدول المقارنة

معايير	مفتاح واجهة برمجة التطبيقات	JWT	OAuth2
وقت التكامل	دقائق	ساعات	أيام
هوية المستخدم	على مستوى الحساب	على مستوى المستخدم (المطالبات)	مستوى المستخدم (النطاقات)
التحقق من عديمي الجنسية	لا (بحث الخادم)	نعم (التحقق من التوقيع)	يعتمد على تنسيق الرمز المميز
سرعة الإلغاء	فوري (مفتاح الحذف)	تأخر (حتى انتهاء الصلاحية)	فوري (إلغاء الرمز المميز)
الوصول المفوض	لا	لا	نعم
دعم طرف ثالث	فقير	جيد	ممتاز
مناسبة للمتصفحات	لا (التعرض الرئيسي)	نعم (قصيرة الأجل)	نعم (رمز التفويض + PKCE)

إطار القرار: اختر بناءً على حالة الاستخدام الخاصة بك

توقف عن السؤال "ما هو الأكثر أمانًا؟" الثلاثة كلها آمنة عند استخدامها بشكل صحيح. الحق السؤال: "من يتصل بواجهة برمجة التطبيقات (API) الخاصة بي ولماذا؟"

• الخادم يستدعي الخادم، لا يوجد مستخدم متورط: مفتاح واجهة برمجة التطبيقات. مكالمات الواجهة الخلفية الخاصة بك أ واجهة برمجة تطبيقات الأداة المساعدة لعمليات بحث DNS أو التجزئة أو التحقق من صحة البيانات. مفتاح واحد، رأس واحد، تم الانتهاء منه.
• يقوم تطبيقك الخاص بمصادقة المستخدمين لديك: JWT. تطبيق الهاتف المحمول الخاص بك أو SPA يرسل طلبات نيابة عن مستخدم قام بتسجيل الدخول. قم بالتوقيع على JWT قصير الأجل عند تسجيل الدخول، والتحقق منه على كل طلب دون مخزن الجلسة.
• تصل تطبيقات الطرف الثالث إلى بيانات المستخدم: OAuth2. بناء المطورين الخارجيين التكامل مع النظام الأساسي الخاص بك. يتحكم المستخدمون في ما يمكن لكل تطبيق الوصول إليه من خلال النطاق شاشات الموافقة

إدارة مفاتيح API على نطاق واسع باستخدام Unkey

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

غير مفتاح هو مفتوح خدمة إدارة مفاتيح واجهة برمجة التطبيقات المصدرية التي تتعامل مع الإنشاء والتحقق وتحديد المعدل و تحليلات. يستخدم botoi Unkey لإدارة جميع مفاتيح API عبر أكثر من 150 نقطة نهاية.

قم بإنشاء مفتاح محدد النطاق مع تحديد معدل مضمن:

import { Unkey } from "@unkey/api";

const unkey = new Unkey({ rootKey: process.env.UNKEY_ROOT_KEY });

// Create a scoped API key with built-in rate limiting
const key = await unkey.keys.create({
  apiId: "api_your_api_id",
  prefix: "botoi",
  meta: { userId: "user_12345", plan: "pro" },
  expires: Date.now() + 90 * 24 * 60 * 60 * 1000, // 90 days
  ratelimit: {
    type: "fast",
    limit: 100,
    refillRate: 10,
    refillInterval: 1000,
  },
});

// key.result.key = "botoi_3xK9m2..."

التحقق من ذلك في الوسيطة الخاصة بك:

import { verifyKey } from "@unkey/api";

async function authMiddleware(req, res, next) {
  const apiKey = req.headers["x-api-key"];
  if (!apiKey) return res.status(401).json({ error: "Missing API key" });

  const result = await verifyKey(apiKey);

  if (!result.result.valid) {
    return res.status(result.result.code === "RATE_LIMITED" ? 429 : 403)
      .json({ error: result.result.code });
  }

  req.keyMeta = result.result.meta; // { userId, plan }
  next();
}

يقوم Unkey بتخزين المفاتيح المجزأة (ليس في نص عادي أبدًا)، ويفرض حدودًا للمعدل على الحافة، ويعطيها لديك لوحة تحكم تحليلية توضح الاستخدام لكل مفتاح. عندما يحتاج المفتاح إلى التدوير، قم بإنشاء مفتاح جديد وتعيين انتهاء الصلاحية على القديم. لا يوجد توقف، ولا تغييرات في التعليمات البرمجية.

قائمة التحقق الأمنية لكل نهج

مفاتيح واجهة برمجة التطبيقات

• أرسل عبر HTTPS فقط. لا تقم أبدًا بتضمين المفاتيح في عناوين URL أو سلاسل الاستعلام.
• تخزين مجزأة على الخادم. لا تقم أبدًا بتسجيل المفاتيح الأولية.
• نطاق المفاتيح لأذونات محددة (للقراءة فقط، والكتابة، والمسؤول).
• تحديد تواريخ انتهاء الصلاحية. فرض التناوب كل 90 يومًا.
• استخدم رأسًا مخصصًا (x-api-key) بدلاً من Authorization ل تجنب التخزين المؤقت لبيانات اعتماد المتصفح.

JWTs

• استخدم التوقيع غير المتماثل (RS256 أو ES256). لا تستخدم أبدًا HS256 مع سر مشترك الأنظمة الموزعة.
• اجعل عمر الرمز قصيرًا: 5-15 دقيقة لرموز الوصول.
• التحقق من صحة iss, aud، و exp المطالبات على كل طلب.
• نشر المفاتيح العامة عبر نقطة نهاية JWKS. تدوير مفاتيح التوقيع على جدول زمني.
• لا تقم مطلقًا بتخزين البيانات الحساسة في الحمولة. JWTs مشفرة وليست مشفرة.

OAuth2

• استخدم تدفق رمز التفويض مع PKCE لجميع العملاء، بما في ذلك SPA والهواتف المحمولة apps.
• لا تستخدم أبدًا التدفق الضمني. لقد تم إهماله في OAuth 2.1 لسبب وجيه.
• تخزين أسرار العميل على الخادم فقط. لا تقم أبدًا بشحنها في تطبيقات الهاتف المحمول أو الواجهة الأمامية كود.
• التحقق من صحة state المعلمات لمنع هجمات CSRF على عنوان URL لرد الاتصال.
• استخدم رموز الوصول قصيرة العمر مع تدوير رمز التحديث.

النقاط الرئيسية

• مفاتيح واجهة برمجة التطبيقات هي الاختيار الصحيح لواجهات برمجة التطبيقات الخاصة بالأداة المساعدة من خادم إلى خادم. إنهم كذلك سريع التكامل، وسهل الإدارة، وكافي عند عدم الحاجة إلى هوية المستخدم. botoi يستخدمها عبر أكثر من 150 نقطة نهاية مع Unkey للإدارة.
• JWTs هي الخيار الصحيح لجلسات المستخدم عديمي الجنسية. إنهم يقضون عمليات البحث في مخزن الجلسة على نطاق واسع، لكن إبطال الرمز المميز يحتاج إلى بنية تحتية إضافية.
• OAuth2 هو الخيار الصحيح عندما تحتاج تطبيقات الطرف الثالث إلى وصول واسع النطاق موارد المستخدم. يتم تبرير التعقيد من خلال نموذج الأمان الذي يوفره.
• اختر بناءً على المتصل، وليس على الضجيج. تمت هندسة واجهة برمجة التطبيقات المساعدة مع OAuth2 بشكل مفرط. أ لا يمكن لواجهة برمجة تطبيقات النظام الأساسي التي تحتوي على مفاتيح واجهة برمجة التطبيقات فقط منح الوصول المفوض.
• اجمع بين الأساليب عندما يتطلب منتجك ذلك. مفاتيح API للتكامل المباشر، OAuth2 لشركاء السوق، JWTs لجلسات المستخدم التي تم تسجيل دخولها.