مفتاح API لـ App Store Connect (.p8): الإنشاء والاستخدام

يتيح مفتاح API لـ App Store Connect لأداة مثل EAS أو fastlane أو RevenueCat أو سكربتك الخاص أن تعمل على حسابك دون كلمة المرور ودون المصادقة الثنائية. تحتفظ Apple بالنصف العام من المفتاح، وتنزّل أنت النصف الخاص، وهو ملف .p8، مرة واحدة فقط. بهذا الملف ومعه Issuer ID وKey ID توقّع رموزًا (tokens) صالحة لمدة 20 دقيقة كحد أقصى لمعظم الطلبات.

أنشر تطبيقاتي على iOS، ومنها TradaZen وNolera، باستخدام Expo. لدي مفتاح فريق بدور App Manager يستخدمه RevenueCat وبنائي على Expo وأداة سطر أوامر أعدّل بها صفحات تطبيقاتي. يعتمد هذا الدليل على صفحات Apple وExpo وfastlane التي راجعتها في 3 نوفمبر 2026. لا تخلط بينه وبين مفاتيح الخدمات الموضوعة داخل كود التطبيق: تلك أتحدث عنها في مفتاح API سري في تطبيق Expo.

ما الذي يفعله مفتاح API لـ App Store Connect

بحسب توثيق Apple، تتطلب واجهة App Store Connect API رمز JWT مع كل طلب. أنت تولّده وتوقّعه بمفتاحك الخاص. المفتاح مخصص لهذه الواجهة فقط: لا يمكنك استخدامه مع خدمات Apple الأخرى.

فائدته في جملة واحدة: لا يحتاج أي شخص إلى تأكيد تسجيل الدخول. معرّف Apple الخاص بك يصطدم بالمصادقة الثنائية، وهذا يمنع أي أتمتة. يوضح دليل EAS Submit على iOS ما يغيّره ذلك عند إرسال تطبيق Expo.

قبل كل شيء: اطلب الوصول إلى الواجهة

لا يمكنك إنشاء المفتاح الأول مباشرة. مساعدة App Store Connect واضحة: يجب أن يطلب الـ Account Holder الوصول إلى الواجهة أولًا. يفتح Users and Access، ثم ينقر على Integrations، ثم على Request Access. تدرس Apple كل طلب على حدة.

الـ Account Holder هو الشخص الذي سجّل الحساب. إن كنت مبتدئًا فهو أنت: يشرح دليل حساب مطوّر Apple خطوات التسجيل.

مفتاح فريق أم مفتاح فردي

تقدّم Apple نوعين من المفاتيح. هذه الفروق بينهما، كما وردت في التوثيق ومساعدة App Store Connect:

المعيار	مفتاح الفريق	المفتاح الفردي
من يستطيع توليده	Account Holder أو Admin	كل مستخدم تقريبًا
التطبيقات المتاحة	جميعها دون استثناء	تطبيقات المستخدم
الصلاحيات	الدور المختار	صلاحيات المستخدم
عدد المفاتيح	عدة مفاتيح	مفتاح نشط واحد لكل شخص
الشهادات والملفات التعريفية	نعم، حسب الدور	لا
المبيعات والمالية وnotaryTool	حسب الدور	لا
حقل الرمز	iss = Issuer ID	sub = user

«كل مستخدم تقريبًا» تعني بحسب Apple: Account Holder وAdmin وApp Manager وCustomer Support وDeveloper وMarketing، إلا إذا سحب منهم Admin أو الـ Account Holder صلاحية توليد مفتاح فردي.

مع Expo أو fastlane، اختر مفتاح فريق. المفتاح الفردي لا يصل إلى نقاط الواجهة الخاصة بالتجهيز (provisioning)، أي تلك التي تنشئ الشهادات والملفات التعريفية. ويؤكد ذلك توثيق fastlane: مفاتيح الفريق مطلوبة لأي وصول مرتبط بالتجهيز.

أي دور تعطي مفتاحك

مفتاح الفريق يصل إلى كل تطبيقات الحساب أيًّا كان دوره. الدور يحدد ما يستطيع فعله. تحذّر Apple من أن مفتاحًا بدور Admin يستطيع إنشاء المستخدمين وحذفهم: أعطِ أصغر دور يغطي استخدامك. الصلاحيات أدناه مأخوذة من جدول الأدوار لدى Apple.

استخدام المفتاح	الأدوار التي تسمح به
إرسال البناءات (builds)	Admin, App Manager, Developer
إدارة بناءات TestFlight	Admin, App Manager
إنشاء الشهادات والملفات التعريفية	Admin, App Manager
إرسال تطبيق للمراجعة	Admin, App Manager
استيراد المنتجات والأسعار (RevenueCat)	App Manager على الأقل
توليد مفاتيح فريق أخرى	Admin

سطر RevenueCat مأخوذ من توثيقه. أما دليل Expo فـيعطي المفتاح دور Admin. في تطبيقاتي يكفي دور App Manager: به ينشئ EAS ملفات التوزيع التعريفية، ويستورد RevenueCat المنتجات.

بعد توليد المفتاح، لا يمكنك تعديل اسمه ولا دوره. لتغييرهما، عليك إلغاؤه وتوليد مفتاح آخر.

إنشاء مفتاح فريق خطوة بخطوة

تحتاج إلى حساب Admin أو Account Holder. بحسب Apple:

1. افتح Users and Access، ثم تبويب Integrations.
2. اختر App Store Connect API من العمود الأيسر، ثم تبويب Team Keys.
3. انقر على Generate API Key، أو على زر +.
4. أعطِ المفتاح اسمًا. الاسم لك فقط، وليس جزءًا من المفتاح. سمّه باسم الأداة التي ستستخدمه.
5. اختر الدور تحت Access، ثم انقر على Generate.
6. نزّل المفتاح الخاص عبر رابط Download API Key.

يختفي رابط التنزيل بمجرد تنزيل الملف، ولا تحتفظ Apple بأي نسخة منه. احفظ ملف .p8 قبل إغلاق الصفحة.

بعدها دوّن المعرّفين. بحسب صفحة Apple عن الرموز، يظهر Issuer ID أعلى صفحة Integrations، مع زر Copy. ويظهر Key ID في قائمة المفاتيح النشطة: مرّر المؤشر فوقه ليظهر Copy Key ID. الـ Issuer ID واحد لكل مفاتيح الفريق في الحساب. أما Key ID فخاص بكل مفتاح.

للمفتاح الفردي الأمر أقصر: افتح ملفك الشخصي كمستخدم، وانزل إلى Individual API Key وانقر على Generate API Key. التنزيل هنا أيضًا يتم مرة واحدة فقط.

حفظ ملف .p8

تطلب Apple أن تعامل المفتاح ككلمة مرور: لا تشاركه، ولا تضعه في مستودع كود، ولا تدمجه أبدًا في كود تطبيق. هذه طريقتي:

• مجلد خارج المشروع، أو مدير الأسرار في أداة التكامل المستمر لديك.
• مجلد المفاتيح في ملف .gitignore، إن كان على الملف أن يبقى داخل المشروع أثناء الإرسال.
• صلاحيات صارمة. رفضت أداة سطر أوامر لـ App Store Connect ملف .p8 الخاص بي ما دام قابلًا للقراءة من حسابات أخرى. حلّ أمر chmod 600 المشكلة.
• مفتاح لكل أداة. تسمح Apple بـتوليد عدة مفاتيح، بالأدوار التي تختارها.

هذه النقطة الأخيرة لم أطبّقها في البداية. مفتاحي بدور App Manager يخدم RevenueCat وبنائي وأداة الصفحات معًا. إن اضطررت لإلغائه، تتوقف الأدوات الثلاث معًا. لو أعدت الأمر، لأنشأت مفتاحًا لكل أداة، لأتمكن من إيقاف واحد دون المساس بالبقية.

استخدامه مع Expo

ثلاث طرق لإعطاء المفتاح لـ EAS:

• اترك EAS يديره. يستطيع eas credentials --platform ios إنشاء مفتاح وحفظه على خوادم Expo. هذا أبسط طريق.
• صرّح به في eas.json. يقبل ملف التعريف submit الحقول ascApiKeyPath وascApiKeyIssuerId وascApiKeyId. بحسب مرجع eas.json، تقبل هذه الحقول متغيرات بيئة مثل $ASC_API_KEY_PATH.
• مرّره عبر البيئة. يوثّق مستودع EAS CLI المتغيرات EXPO_ASC_API_KEY_PATH وEXPO_ASC_KEY_ID وEXPO_ASC_ISSUER_ID. مع المفتاح الفردي، تحذف Issuer ID.

قيد يجب معرفته في البناء: توضّح Expo أن الواجهة الرسمية لا تستطيع ربط App Group أو Merchant ID أو حاوية CloudKit. تحتاج حينها إلى تسجيل الدخول بمعرّف Apple الخاص بك، محليًا. عشت هذا مع Nolera ومجموعة التطبيقات الخاصة بالـ widget: فعّل المفتاح القدرة دون أن يربط المجموعة. قمت بهذا الربط في بوابة مطوّري Apple. إن تعطلت مزامنة القدرات، فإن EXPO_NO_CAPABILITY_SYNC=1 يعطّلها، وتفعّل أنت القدرة يدويًا على معرّف التطبيق. توقيع البناءات مشروح في شهادة iOS والـ provisioning profile.

استخدامه مع fastlane

يقرأ fastlane المفتاح من ملف JSON. الحقول key_id وissuer_id وkey، أي محتوى ملف .p8، إلزامية. أما duration وin_house فاختيارية. قيم وهمية:

{
  "key_id": "XXXXXXXXXX",
  "issuer_id": "your-issuer-id",
  "key": "-----BEGIN PRIVATE KEY-----\nMIGT...\n-----END PRIVATE KEY-----",
  "duration": 1200,
  "in_house": false
}

بعدها تمرّر هذا الملف إلى أحد الإجراءات، مثلًا fastlane pilot distribute --api_key_path fastlane/cle.json. وفي ملف Fastfile، يأخذ الإجراء app_store_connect_api_key الحقول key_id وissuer_id وkey_filepath. مدة الجلسة لا تتجاوز 1200 ثانية، أي 20 دقيقة. لا تدعمها كل الإجراءات: تشير fastlane مثلًا إلى أن produce وpem لا يعملان بمفتاح API.

استخدامه في سكربتك الخاص

دون أداة، تصنع الرمز بنفسك. تحدد Apple الوصفة:

• الترويسة: alg قيمته ES256، وkid قيمته Key ID الخاص بك، وtyp قيمته JWT.
• المحتوى، مفتاح فريق: iss هو Issuer ID الخاص بك؛ iat وقت الإنشاء؛ exp وقت الانتهاء؛ aud وقيمته appstoreconnect-v1.
• المحتوى، مفتاح فردي: sub قيمته user بدلًا من iss.
• المدة: بعد 20 دقيقة، ترفض Apple الرمز في معظم الطلبات.

بلغة Python، مع مكتبة PyJWT وتبعيتها التشفيرية، تُثبَّت بالأمر pip install pyjwt[crypto] بحسب توثيقها. في طرفية Mac ضع علامات تنصيص: pip install "pyjwt[crypto]"، وإلا يرفض zsh الأقواس المربعة.

import time
import jwt

KEY_ID = "XXXXXXXXXX"
ISSUER_ID = "your-issuer-id"

with open("AuthKey_XXXXXXXXXX.p8") as f:
    private_key = f.read()

now = int(time.time())
token = jwt.encode(
    {"iss": ISSUER_ID, "iat": now, "exp": now + 20 * 60, "aud": "appstoreconnect-v1"},
    private_key,
    algorithm="ES256",
    headers={"kid": KEY_ID, "typ": "JWT"},
)
print(token)

ثم ترسله في ترويسة Authorization، كما في مثال Apple:

curl -H "Authorization: Bearer $TOKEN" "https://api.appstoreconnect.apple.com/v1/apps"

شغّلت هذا السكربت في 3 نوفمبر 2026 بمفتاح مؤقت ولّدته على جهازي: ترويسة الرمز ومحتواه يطابقان صفحة Apple، وتوقيع ES256 يتحقق بنجاح. لم أرسله إلى واجهة Apple بهذا المفتاح التجريبي، لأنه غير موجود لدى Apple. أعد استخدام الرمز نفسه ما دام صالحًا: تنصح Apple بذلك لأداء أفضل.

إلغاء مفتاح

ألغِ المفتاح بمجرد ضياعه أو تسرّبه، أو حين تتوقف أداة عن استخدامه. بحسب مساعدة App Store Connect، بحساب Account Holder أو Admin:

1. افتح Users and Access، ثم Integrations.
2. اختر Team Keys أو Individual Keys، ثم انقر على Edit.
3. حدّد المفاتيح المراد إلغاؤها، ثم Revoke Key.
4. أكّد بـ Revoke.

المفتاح الملغى لا يُعاد تفعيله أبدًا. تعرضه Apple لمدة 30 يومًا تحت Revoked. وتفشل حينها المصادقة في كل أداة كانت تستخدمه. مع Expo تكون الرسالة «App Store Connect rejected the API authentication credentials». هذه الرسالة وغيرها من أخطاء الإرسال مشروحة في أخطاء الإرسال مع EAS وطريقة إصلاحها. إن لم يكن المفتاح مسرّبًا، جهّز المفتاح الجديد قبل إيقاف القديم. وإن كان مسرّبًا، فتطلب Apple إلغاءه فورًا.

لمفتاحك الفردي: ملفك الشخصي، ثم Individual API Key، ثم Revoke.

قائمة التحقق الخاصة بي لمفتاح .p8

• طلب الـ Account Holder الوصول إلى الواجهة.
• المفتاح مفتاح فريق إن كان يخدم البناءات أو الملفات التعريفية.
• دوره أصغر دور يغطي الاستخدام، واسمه يقول أي أداة تستخدمه.
• ملف .p8 محفوظ خارج المستودع، بصلاحيات صارمة ونسخة احتياطية مشفّرة.
• Issuer ID وKey ID مدوّنان بشكل منفصل، دون الملف.
• لكل أداة مفتاحها، لتتمكن من إلغاء مفتاح واحد فقط.

أتمتة النشر دون أن تفقد مفتاحك

المفتاح مجرد قطعة في المسار. ينطلق iOS & Android Kit من الكود الأساسي لتطبيقاتي، بما فيه الاشتراكات، ويمر بأربع مراحل حتى App Store، بالسرعة التي تناسبك. وإن ربطت RevenueCat بهذا المفتاح، فالإعداد الكامل موجود في RevenueCat والاشتراك داخل التطبيق على iOS.

إن كنت تجهّز إطلاقك الأول، قم بالتشخيص المجاني: يخبرك بما يعيقك فعلًا ويرسل لك قائمتي لتجنّب رفض Apple. وتستعرض صفحة نشر تطبيق على App Store كل مرحلة، من صفحة التطبيق إلى الموافقة.

الأسئلة الشائعة

كيف أنشئ مفتاح API لـ App Store Connect؟

يطلب الـ Account Holder أولًا الوصول إلى الواجهة. بعدها يفتح Admin قائمة Users and Access، تبويب Integrations، ثم App Store Connect API، ثم Team Keys. ينقر على Generate API Key، ويختار اسمًا ودورًا، ويولّد المفتاح، ثم ينزّل ملف .p8.

هل يمكن إعادة تنزيل ملف .p8 ضائع؟

لا. يُنزَّل الملف مرة واحدة فقط، ولا تحتفظ Apple بأي نسخة منه. ألغِ المفتاح الضائع، ثم ولّد مفتاحًا جديدًا وحدّث كل أداة كانت تستخدمه.

أين أجد Issuer ID وKey ID؟

في App Store Connect، قائمة Users and Access، تبويب Integrations. يظهر Issuer ID أعلى الصفحة. ويظهر Key ID في قائمة المفاتيح النشطة. المفتاح الفردي لا يستخدم Issuer ID.

أي دور أعطي مفتاحًا يستخدمه Expo؟

يعطي دليل Expo دور Admin. وبحسب جدول الأدوار لدى Apple، يكفي App Manager لإرسال البناءات وإنشاء الشهادات والملفات التعريفية. وهو دور مفتاحي الذي أستخدمه لبناءاتي على Expo.

هل يمكن تغيير دور مفتاح API؟

لا. لا تسمح Apple بتعديل اسم المفتاح ولا دوره بعد إنشائه. ألغِه، ثم ولّد مفتاحًا جديدًا بالدور الصحيح.

هل تنتهي صلاحية مفتاح API لـ App Store Connect؟

لا تذكر صفحات Apple أي انتهاء لصلاحية المفتاح، بل إلغاءه فقط. الرموز الموقّعة به هي التي تنتهي صلاحيتها، بعد 20 دقيقة كحد أقصى لمعظم الطلبات.