لمن هذا

أنت تبني تطبيقًا (playground، agent، عميل جوال، …) وتريد أن يربط مستخدموك حسابهم في Airforce حتى يتمكنوا من تشغيل الدردشة أو توليد الصور عبر واجهتك دون مشاركة مفتاح API الخام معك. استخدم هذا التدفق.

ستحصل على access_token غير شفاف (24h TTL) محدود بما طلبه تطبيقك ووافق عليه المستخدم. استخدمه كرأس Bearer مقابل /v1/* أو نقاط نهاية /oauth/userinfo.

1. احصل على client_id + client_secret

Phase 1 هو تسجيل يديره المسؤول. تواصل معنا بـ:

اسم التطبيق (يُعرض لمستخدميك على شاشة الموافقة)
وصف من جملة واحدة
عنوان URL للصفحة الرئيسية (اختياري، يُعرض على الموافقة)
عنوان URL لشعار مربع (اختياري)
redirect_uri واحد أو أكثر بشكل دقيق (فقط https://، باستثناء http://localhost للتطوير)
ما الـ scopes التي تحتاجها (انظر أدناه)

نُرسل إليك client_id و client_secret. احفظ الـ secret من جانب الخادم — إذا كنت SPA خالصًا / تطبيقًا أصليًا بدون backend، يمكنك تخطي الـ secret والاعتماد على PKCE وحده.

2. Scopes

Scope	ما يمنحه
profile	يقرأ كائن user عبر /oauth/userinfo (id، username، plan، الإيميلات المرتبطة عند التحقق منها).
chat	POST /v1/chat/completions, /v1/messages, /v1/messages/count_tokens, /v1/responses.
images	POST /v1/images/generations.
keys:read	محجوز — يُدرج مفاتيح Airforce API للمستخدم (Phase 2).
keys:write (حساس)	محجوز — ينشئ + يلغي مفاتيح Airforce API للمستخدم (Phase 2). scope حساس.

تُفصل scopes المتعددة بمسافات في معامل الاستعلام scope : scope=profile chat images.

3. التدفق

3.1 توليد زوج PKCE

في عميلك، قبل إعادة التوجيه إلى /oauth/authorize، ولّد verifier عشوائيًا وchallenge SHA-256 المطابق.

// In your app, before redirecting to /oauth/authorize:
const verifier = randomString(64); // 43..128 chars [A-Z][a-z][0-9]-._~
const challenge = base64UrlNoPad(sha256(verifier));
sessionStorage.setItem('airforce_pkce_verifier', verifier);

3.2 إعادة التوجيه إلى /oauth/authorize

ابنِ عنوان URL للتفويض وأرسل المستخدم إلى هناك. سيرى شاشة الموافقة الخاصة بنا، ويقرر، ويُعاد توجيهه إليك.

https://api.airforce/oauth/authorize?
  response_type=code
  &client_id=airforce_xxxxxxxxxxxxxxxxxxxxxxxxx
  &redirect_uri=https://your.app/oauth/callback
  &scope=profile chat
  &state=<random opaque>
  &code_challenge=<base64url(sha256(verifier))>
  &code_challenge_method=S256

يصل المستخدم إلى شاشة الموافقة الخاصة بنا، يسجل الدخول (إذا لم يكن قد فعل بعد)، ثم يوافق أو يرفض. نُعيد التوجيه إلى redirect_uri الخاص بك مع ?code=… قصير الأجل عند الموافقة، ?error=access_denied عند الرفض. الـ state الأصلي يُعاد — تحقق من تطابقه.

3.3 استبدال code بـ access_token

من backend الخاص بك، استبدل الـ code (بالإضافة إلى PKCE verifier) مقابل access token.

curl -X POST https://api.airforce/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=$CODE" \
  --data-urlencode "redirect_uri=https://your.app/oauth/callback" \
  --data-urlencode "code_verifier=$VERIFIER"

الاستجابة (24h TTL):

{
  "access_token": "airf_oat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "profile chat"
}

3.4 استخدام الـ token

استدعِ نقطة نهاية userinfo أو أي مسار /v1/* تسمح به الـ scopes الممنوحة:

# Profile lookup
curl https://api.airforce/oauth/userinfo \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Chat (requires scope=chat)
curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hi"}]}'

استجابة /oauth/userinfo

{
  "id": "user-uuid",
  "username": "foo",
  "plan": "free",
  "is_admin": false,
  "email": "[email protected]",
  "email_verified": true,
  "github_email": "[email protected]",
  "discord_username": "foo#1234"
}

تظهر حقول مثل email, github_email, discord_username فقط عندما يكون المستخدم قد تحقق منها / ربطها فعلًا. خطط للوجود والغياب.

إلغاء token

عندما يسجل المستخدم الخروج من تطبيقك، ألغِ الـ token حتى لا يستمر في تحميل حسابه في الخلفية:

curl -X POST https://api.airforce/oauth/revoke \
  --data-urlencode "token=$ACCESS_TOKEN"

RFC 7009. تُعيد دائمًا 200 بغض النظر عما إذا كان الـ token موجودًا (بدون oracle).

ملاحظات أمنية

PKCE إلزامي للعملاء العامين (بدون client_secret على جانب الخادم). نقبل فقط S256 — code_challenge_method=plain مرفوض.
redirect_uri هو تطابق دقيق. لا يوجد تطابق بادئة / wildcard. إذا كنت تحتاج بيئات متعددة، سجّل URI واحد لكل بيئة.
للـ tokens 24h TTL ولا توجد بعد refresh tokens — عند انتهاء الصلاحية، مرّر المستخدم عبر /oauth/authorize مرة أخرى. للوكلاء طويلي الأمد، اطلب عند البدء واحفظ الـ token في تخزين آمن.
لا تخزن client_secret في كود جانب العميل. إذا كان تطبيقك SPA متصفح فقط أو عميل أصلي، سجّل بدون خادم واعتمد على PKCE.
يمكن للمستخدمين إلغاء تطبيقك في أي وقت من dashboard → علامة Apps. تعامل مع 401 بإعادة تشغيل تدفق OAuth.
تغطية Phase 1: tokens bearer OAuth تعمل على /v1/chat/completions, /v1/messages, /v1/messages/count_tokens, /v1/responses, /v1/images/generations, و /oauth/userinfo. نقاط نهاية الصوت والفيديو والصوت وcharacter لا تزال تتطلب مفتاح Airforce API عادي في Phase 1.

التسجيل

أرسل بريدًا إلى [email protected] أو تواصل معنا على Discord مع تفاصيل التسجيل المذكورة أعلاه. سنرسل إليك بياناتك خلال بضع ساعات.

تسجيل الدخول باستخدام Airforce