ابنِ على الشبكة

1. 1

   أنشئ مفتاحًا في إعدادات المطوّر. امنحه اسمًا ونطاقات الصلاحية التي يحتاجها فقط، وتاريخ انتهاء إن كان لغرض مؤقت.

   إلى أن يتأكّد بريدك الإلكتروني، لا يحمل المفتاح إلا نطاقات القراءة.

2. 2

   انسخ المفتاح حين يظهر. فهو لا يظهر إلا مرة واحدة: لا نحتفظ إلا ببصمة منه، فالمفتاح المفقود لا يُستعاد بل يُستبدل.

3. 3

   أرسله رمزًا من نوع bearer مع كل طلب:

   shell

   curl https://api.thecubefloor.com/v1/me \
     -H "Authorization: Bearer dk_…"

   نسخ
4. 4

   ألغِه من الصفحة نفسها حالما تنتهي الحاجة إليه. تُظهر القائمة آخر استخدام لكل مفتاح.

منح رمز التفويض، مع PKCE (S256) إلزاميًا في كل طلب. كل تطبيق عميل سرّي يملك سرًّا خاصًا به.

1. 1

   سجّل التطبيق في إعدادات المطوّر: اسمه (يراه الناس حين يُطلب إذنهم)، وعناوين إعادة التوجيه، ونطاقات الصلاحية التي يحق له طلبها. تحصل على client_id وclient_secret، ويظهر السرّ مرة واحدة. يتطلّب تسجيل تطبيق بريدًا إلكترونيًا مؤكّدًا.

   يجب أن تطابق عناوين إعادة التوجيه حرفًا بحرف. وهي عناوين https:// كاملة بلا جزء بعد العلامة #؛ ولا يُقبل http:// العادي إلا نحو localhost أو عنوان الحلقة المحلية، للتطوير والتطبيقات الأصلية.

2. 2

   أنشئ code_verifier عشوائيًا ووجّه متصفح الشخص إلى /oauth/authorize مع بصمته SHA-256 في code_challenge:

   shell

   # المُتحقِّق: من 43 إلى 128 حرفًا غير محجوز. احتفظ به حتى الاستبدال.
   CODE_VERIFIER=$(openssl rand -base64 64 | tr -dc 'A-Za-z0-9' | cut -c1-64)
   CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary \
     | openssl base64 -A | tr '+/' '-_' | tr -d '=')
   
   https://api.thecubefloor.com/oauth/authorize?response_type=code
     &client_id=app_…
     &redirect_uri=https%3A%2F%2Fyour.app%2Fcallback
     &scope=account%3Aread%20jobs%3Aread
     &state=…
     &code_challenge=$CODE_CHALLENGE
     &code_challenge_method=S256

   نسخ
3. 3

   يرى صفحة الموافقة الخاصة بنا على thecubefloor.com، وفيها اسم تطبيقك وما يطلبه والمكان الذي سيعود إليه. إن وافق، يعود المتصفح إلى عنوان إعادة التوجيه ومعه code وstate الخاص بك؛ وإن رفض، يعود ومعه error=access_denied.

4. 4

   استبدل الرمز بالرموز خلال دقيقة واحدة ولمرة واحدة فقط. صادِق عبر HTTP Basic أو بإرسال client_id وclient_secret في النموذج:

   shell

   curl https://api.thecubefloor.com/oauth/token \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     -d grant_type=authorization_code \
     -d code="$CODE" \
     -d redirect_uri=https://your.app/callback \
     -d code_verifier="$CODE_VERIFIER"

   نسخ
5. 5

   يتضمّن الرد رمز وصول (do_…، صالح لساعة) ورمز تجديد (dr_…، ثلاثون يومًا). كل تجديد يستهلك رمز التجديد ويعيد زوجًا جديدًا؛ وتقديم رمز مستهلك يُنهي كل الرموز الناشئة عن الموافقة نفسها، لأن أحد حامليه لص.

   json · shell

   {
     "access_token": "do_…",
     "token_type": "Bearer",
     "expires_in": 3600,
     "refresh_token": "dr_…",
     "scope": "account:read jobs:read"
   }
   
   curl https://api.thecubefloor.com/oauth/token \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     -d grant_type=refresh_token \
     -d refresh_token="$REFRESH_TOKEN"

   نسخ
6. 6

   حين يقطع الشخص الاتصال في تطبيقك، أعِد الرمز (RFC 7009). رمز التجديد يُنهي الموافقة كلها:

   shell

   curl https://api.thecubefloor.com/oauth/revoke \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     -d token="$REFRESH_TOKEN"

   نسخ