مفاتيح الـ API والصلاحيات

للمفتاح صلاحيات بصيغة app:resource:action، ولا يستطيع أبدا أن يغير طريقة الدخول إلى الحساب، ويستبدل بـ token قصير العمر عبر HTTP.

كل الصفحات

استخدام المفتاح عبر HTTP

الـ CLI يجري هذا الاستبدال عنك. ومن دونه، استبدل مفتاحك بـ token في نداء واحد. أرسل المفتاح في الـ header Authorization:

تيرمينال
curl -sX POST https://auth.api.ghaym.me/v1/auth/token -H "Authorization: Bearer $GHAYM_TOKEN"

يحتوي الرد على access token:

json
{
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "cloud:projects:read cloud:projects:deploy"
}

احفظ قيمة access_token، هنا باسم ACCESS_TOKEN، وأرسلها مع كل نداء:

تيرمينال
curl -s https://cloud.api.ghaym.me/v1/projects -H "Authorization: Bearer $ACCESS_TOKEN"
ملاحظة

لا تخلط بينهما. GHAYM_TOKEN يحمل مفتاح ghk_ طويل العمر، وترسله إلى نداء الاستبدال فقط. أما الـ access token فترسله مع كل نداء آخر.

  • أرسل المفتاح في الـ header Authorization فقط. لا تضعه في رابط ولا في الـ body الخاص بالطلب، حتى لا يظهر في السجلات.
  • الـ access token قصير العمر، ولا يمكن تجديده. لكي تحصل على واحد جديد، استبدل المفتاح مرة أخرى.
  • تستطيع استبدال المفتاح 30 مرة في الدقيقة. احتفظ بالـ token حتى تنتهي صلاحيته، بدل أن تستبدل المفتاح قبل كل نداء.
  • الـ token يفعل ما تسمح به صلاحيات المفتاح، لكن فقط ما يستطيع صاحب المفتاح فعله اليوم.

ترجع الأخطاء بصيغة RFC 9457. اعرض detail للشخص بدل أن تعيد المحاولة دون فهم. وكل الأنواع موجودة في أخطاء الـ API.

الصلاحيات

للصلاحية ثلاثة أجزاء: app:resource:action. ويمكن أن يكون أي جزء *، ومعناها "الكل".

scope   := segment ":" segment ":" segment | meta
segment := "*" | [a-z0-9-]+
meta    := "read-only"

أمثلة:

  • cloud:projects:deploy: نشر المشاريع، ولا شيء غيره.
  • cloud:projects:*: كل شيء على المشاريع.
  • cloud:*:read: قراءة أي شيء في Cloud.
  • *:*:*: كل ما يستطيع صاحب المفتاح فعله.
  • read-only: كل صلاحيات القراءة والعرض التي يملكها صاحب المفتاح.

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

نصيحة

أعط كل مفتاح أصغر صلاحية تكفي لعمله. مفتاح النشر في الـ CI لا يحتاج إلى *:*:*. ولوحة المتابعة تحتاج إلى read-only فقط.

ما لا يستطيع المفتاح فعله

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

  • أن يضع كلمة سر أو يزيلها.
  • أن يغير البريد الإلكتروني للحساب.
  • أن يحذف الحساب.
  • أن ينشئ مفاتيح API أو يدورها أو يلغيها.

لا يستطيع أي مفتاح فعل ذلك، ولا يوجد إعداد يغير هذا. لهذا لا يفعل المفتاح المسرب إلا ما تسمح به صلاحياته. لا يستطيع الاستيلاء على الحساب، ولا إنشاء مفاتيح أخرى، ولا منع إلغائه.