كيف أُنشئ توكن API للوصول بلا رأس أو للمطوّرين؟

لإنشاء توكن API في VeloCMS، انتقل إلى Admin → Settings → Developer → API Tokens، ثم انقر New Token، واختر نطاقات الصلاحيات التي يحتاجها تكاملك، ثم انقر Generate. انسخ التوكن فورًا — لن يُعرض إلا مرّةً واحدة.

ما نطاقات الصلاحيات التي ينبغي اختيارها لتوكني؟

اختر دائمًا أدنى نطاقات الصلاحيات التي يحتاجها تكاملك فعلًا — فهذا يُحدّ من الضرر في حال تعرَّض التوكن للاختراق. إن كان موقعك الخارجي يحتاج فقط إلى عرض المنشورات المنشورة، فاكتفِ بنطاق «قراءة المنشورات المنشورة». وإن كنت تُشغِّل سكريبت هجرة يحتاج إلى إنشاء منشورات، استخدم «كتابة المنشورات». وإن كنت تبني ميزة مخصصة للأعضاء تحتاج إلى التحقق من الاشتراكات، أضف «قراءة الأعضاء». النطاقات المتاحة هي: قراءة المنشورات المنشورة، وقراءة جميع المنشورات (بما فيها المسوّدات)، وكتابة المنشورات، وقراءة الوسائط، وكتابة الوسائط، وقراءة الأعضاء، وكتابة الأعضاء، وقراءة إعدادات الموقع، وكتابة إعدادات الموقع. ينبغي إنشاء توكنات تملك صلاحية كتابة إعدادات الموقع بحذر شديد، إذ يتيح هذا النطاق تغيير النطاق والسمة وإعدادات الفوترة.

كيف أستخدم التوكن في طلب API؟

أدرج التوكن في ترويسة HTTP Authorization بصيغة Bearer token. في JavaScript أو TypeScript يبدو الأمر كالآتي: fetch('https://your-pb-url/api/collections/posts/records', { headers: { 'Authorization': 'Bearer your-token-here' } }). أما في curl فهو: curl -H 'Authorization: Bearer your-token-here' https://your-pb-url/api/collections/posts/records. في معظم عملاء REST (Postman وInsomnia وHTTPie)، تجد تبويب Authorization مخصصًا تختار منه Bearer Token وتلصق قيمتك فيه.

ماذا يحدث إن أغلقت النافذة دون نسخ التوكن؟

يخزّن VeloCMS بصمة hash أحادية الاتجاه للتوكن لا التوكن نفسه — وذلك تصميمٌ مقصود حتى لا تكشف قاعدة البيانات عن توكناتك حتى في حال اختراقها. وهذا يعني أن إغلاق النافذة دون نسخ التوكن يُعادل فقدانه نهائيًا وعدم إمكانية استعادته. الحل الوحيد هو حذف التوكن القديم وإنشاء توكن جديد، وهو ما يستغرق نحو 30 ثانية ولا يؤثر على التوكنات الأخرى النشطة. من الممارسات الجيدة أن تلصق التوكن المُنشأ حديثًا فورًا في متغيرات بيئة تطبيقك أو مدير الأسرار قبل إغلاق نافذة VeloCMS.

كيف أُلغي توكنًا أو أستبدله بآخر؟

افتح Admin → Settings → Developer → API Tokens. يظهر كل توكن كسطر يحتوي على اسمه وتاريخ إنشائه وتاريخ آخر استخدام وزرًا للإلغاء. انقر Revoke لإبطال التوكن فورًا — ستبدأ طلبات API التي تستخدمه في إرجاع 401 Unauthorized على الفور. لاستبدال توكن (بتوكن جديد مع تقليص فترة التوقف)، أنشئ التوكن الجديد أوّلًا، ثم حدّث تكاملك لاستخدامه، وتحقّق من عمله، ثم أبطل القديم. نمط الاستبدال بدون توقف هذا يتجنّب الفجوة القصيرة التي تحدث لو أبطلت التوكن القديم قبل وضع الجديد في مكانه.