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

لإنشاء توكن API في VeloCMS، انتقل إلى لوحة التحكم ← الإعدادات ← متقدم ← مفاتيح API، وانقر «مفتاح جديد»، واختر نطاقات الصلاحيات التي يحتاجها تكاملك، ثم انقر «إنشاء مفتاح API». انسخ التوكن فورًا — لن يُعرض إلا مرّةً واحدة.

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

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

كيف أستخدم التوكن في طلب 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.

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

افتح لوحة التحكم ← الإعدادات ← متقدم ← مفاتيح API. يظهر كل مفتاح كسطر يحتوي على اسمه ونطاقاته وتاريخ آخر استخدام وزر «حذف المفتاح» (أيقونة سلة المهملات). احذف المفتاح لإبطاله فورًا — ستبدأ طلبات API التي تستخدمه في إرجاع 401 Unauthorized على الفور. لاستبدال توكن (بتوكن جديد مع تقليص فترة التوقف)، أنشئ التوكن الجديد أوّلًا، ثم حدّث تكاملك لاستخدامه، وتحقّق من عمله، ثم أبطل القديم. يتجنّب أسلوب الاستبدال دون توقف هذا الفجوة القصيرة التي كانت ستحدث لو أبطلت التوكن القديم قبل وضع الجديد في مكانه.