Cheie API App Store Connect (.p8): creare și utilizare

O cheie API App Store Connect permite unui tool, cum ar fi EAS, fastlane, RevenueCat sau propriul tău script, să lucreze în contul tău fără parola ta și fără autentificarea în doi pași. Apple păstrează jumătatea publică a cheii, iar tu descarci jumătatea privată, un fișier .p8, o singură dată. Cu acest fișier, cu Issuer ID și cu Key ID, semnezi tokenuri valabile cel mult 20 de minute pentru majoritatea cererilor.

Îmi public aplicațiile iOS, printre care TradaZen și Nolera, cu Expo. O cheie de echipă cu rolul App Manager îmi servește pentru RevenueCat, pentru build-urile Expo și pentru un tool în linie de comandă care îmi editează paginile din store. Ghidul ăsta urmează paginile Apple, Expo și fastlane recitite pe 3 noiembrie 2026. Nu o confunda cu cheile de servicii puse în codul unei aplicații: despre ele vorbesc în cheie API secretă într-o aplicație Expo.

Ce face o cheie API App Store Connect

Conform documentației Apple, API-ul App Store Connect cere un token JWT la fiecare cerere. Îl generezi și îl semnezi cu cheia ta privată. Cheia funcționează doar pentru acest API: n-o poți folosi pentru alte servicii Apple.

Avantajul ei se rezumă într-o frază: nimeni nu trebuie să confirme conectarea. Contul tău Apple se lovește de autentificarea în doi pași, iar asta blochează orice automatizare. Ghidul EAS Submit iOS arată ce schimbă asta la trimiterea unei aplicații Expo.

Înainte de toate: cere acces la API

Prima cheie nu se poate crea din prima. Ajutorul App Store Connect e clar: Account Holder trebuie mai întâi să ceară acces la API. Deschide Users and Access, dă click pe Integrations, apoi pe Request Access. Apple analizează fiecare cerere în parte.

Account Holder e persoana care a înregistrat contul. Dacă ești la început, ești chiar tu: ghidul cont de developer Apple explică înregistrarea în detaliu.

Cheie de echipă sau cheie individuală

Apple oferă două tipuri de chei. Iată diferențele, luate din documentație și din ajutorul App Store Connect:

Criteriu	Cheie de echipă	Cheie individuală
Cine o poate genera	Account Holder sau Admin	Aproape orice utilizator
Aplicații accesibile	Toate, fără excepție	Cele ale utilizatorului
Drepturi	Rolul ales	Cele ale utilizatorului
Număr de chei	Mai multe	Una activă de persoană
Certificate și profiluri	Da, în funcție de rol	Nu
Vânzări, finanțe, notaryTool	În funcție de rol	Nu
Câmpul din token	iss = Issuer ID	sub = user

„Aproape orice utilizator” înseamnă, după Apple: Account Holder, Admin, App Manager, Customer Support, Developer și Marketing, cu excepția cazului în care un Admin sau Account Holder le-a retras dreptul de a genera o cheie individuală.

Pentru Expo sau fastlane, alege o cheie de echipă. O cheie individuală n-are acces la endpointurile de provisioning, cele care creează certificate și profiluri. Documentația fastlane confirmă: cheile de echipă sunt obligatorii pentru orice acces legat de provisioning.

Ce rol să-i dai cheii

O cheie de echipă are acces la toate aplicațiile din cont, indiferent de rol. Rolul decide ce poate face. Apple avertizează că o cheie Admin poate crea și șterge utilizatori: dă-i cel mai mic rol care acoperă ce ai nevoie. Drepturile de mai jos vin din tabelul de roluri Apple.

Utilizarea cheii	Roluri care o permit
Trimiterea build-urilor	Admin, App Manager, Developer
Gestionarea build-urilor TestFlight	Admin, App Manager
Crearea certificatelor și profilurilor	Admin, App Manager
Trimiterea unei aplicații la review	Admin, App Manager
Importul produselor și prețurilor (RevenueCat)	Minimum App Manager
Generarea altor chei de echipă	Admin

Rândul RevenueCat vine din documentația lor. Ghidul Expo, în schimb, îi dă cheii rolul Admin. Pe aplicațiile mele, rolul App Manager e suficient: EAS creează cu el profilurile de distribuție, iar RevenueCat importă produsele.

După ce cheia e generată, nu-i mai poți modifica nici numele, nici rolul. Ca să schimbi ceva, trebuie s-o revoci și să generezi alta.

Crearea unei chei de echipă, pas cu pas

Ai nevoie de un cont Admin sau Account Holder. Conform Apple:

1. Deschide Users and Access, apoi tabul Integrations.
2. Alege App Store Connect API în coloana din stânga, apoi tabul Team Keys.
3. Dă click pe Generate API Key sau pe butonul +.
4. Dă-i un nume cheii. Îți folosește doar ție, nu face parte din cheie. Numește-o după tool-ul care o va folosi.
5. Alege rolul la Access, apoi dă click pe Generate.
6. Descarcă cheia privată cu linkul Download API Key.

Linkul de descărcare dispare imediat după ce ai descărcat fișierul, iar Apple nu păstrează nicio copie. Pune .p8-ul la loc sigur înainte să închizi pagina.

Notează apoi cei doi identificatori. Conform paginii Apple despre tokenuri, Issuer ID apare în partea de sus a paginii Integrations, cu un buton Copy. Key ID apare în lista cheilor active: treci cu mouse-ul peste el ca să apară Copy Key ID. Issuer ID e același pentru toate cheile de echipă din cont. Key ID e unic pentru fiecare cheie.

Pentru o cheie individuală e mai scurt: deschide-ți profilul de utilizator, coboară până la Individual API Key și dă click pe Generate API Key. Și aici descărcarea se face o singură dată.

Unde ții fișierul .p8

Apple cere să tratezi cheia ca pe o parolă: n-o partaja, n-o pune într-un repository de cod, n-o include niciodată în codul unei aplicații. Rutina mea:

• Un folder în afara proiectului, sau managerul de secrete al tool-ului tău de integrare continuă.
• Folderul cheilor în .gitignore, dacă fișierul trebuie să stea în proiect pe durata unei trimiteri.
• Permisiuni stricte. Un tool în linie de comandă pentru App Store Connect mi-a refuzat .p8-ul cât timp fișierul era lizibil de alte conturi. Un chmod 600 a rezolvat problema.
• O cheie per tool. Apple îți permite să generezi mai multe chei, cu rolurile pe care le alegi.

Ultimul punct nu l-am aplicat la început. Cheia mea App Manager servește în același timp pentru RevenueCat, pentru build-uri și pentru tool-ul de pagini. Dacă trebuie s-o revoc, cad trei tool-uri deodată. Dacă ar fi s-o iau de la capăt, aș crea o cheie per tool, ca să pot opri una fără să le ating pe celelalte.

Folosirea ei cu Expo

Trei moduri de a-i da cheia lui EAS:

• Las-o pe mâna EAS. eas credentials --platform ios poate crea o cheie și o poate păstra pe serverele Expo. E calea cea mai simplă.
• Declar-o în eas.json. Profilul submit acceptă ascApiKeyPath, ascApiKeyIssuerId și ascApiKeyId. Conform referinței eas.json, aceste câmpuri acceptă variabile de mediu, ca $ASC_API_KEY_PATH.
• Trimite-o prin mediu. Repository-ul EAS CLI documentează EXPO_ASC_API_KEY_PATH, EXPO_ASC_KEY_ID și EXPO_ASC_ISSUER_ID. Pentru o cheie individuală, omiți Issuer ID.

O limită de știut pentru build-uri: Expo precizează că API-ul oficial nu poate asocia un App Group, un Merchant ID sau un container CloudKit. Atunci ai nevoie de o conectare cu contul tău Apple, local. Am pățit-o pe Nolera cu grupul de aplicații al widgetului: cheia activa capability-ul, dar nu asocia grupul. Am făcut asocierea în portalul de developer Apple. Dacă sincronizarea capability-urilor se blochează, EXPO_NO_CAPABILITY_SYNC=1 o dezactivează, iar tu activezi singur capability-ul pe identificatorul aplicației. Semnarea build-urilor e explicată în certificat și provisioning profile iOS.

Folosirea ei cu fastlane

fastlane citește cheia dintr-un fișier JSON. Câmpurile key_id, issuer_id și key, adică conținutul .p8-ului, sunt obligatorii. duration și in_house sunt opționale. Valori fictive:

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

Apoi dai fișierul unei acțiuni, de exemplu fastlane pilot distribute --api_key_path fastlane/cle.json. Într-un Fastfile, acțiunea app_store_connect_api_key primește key_id, issuer_id și key_filepath. Durata sesiunii nu depășește 1.200 de secunde, adică 20 de minute. Nu toate acțiunile o suportă: fastlane semnalează de exemplu că produce și pem nu funcționează cu o cheie API.

Folosirea ei în propriul tău script

Fără tool, îți faci singur tokenul. Apple stabilește rețeta:

• Header: alg este ES256, kid este Key ID-ul tău, typ este JWT.
• Conținut, cheie de echipă: iss, Issuer ID-ul tău; iat, momentul creării; exp, momentul expirării; aud, care este appstoreconnect-v1.
• Conținut, cheie individuală: sub este user în loc de iss.
• Durată: peste 20 de minute, Apple respinge tokenul pentru majoritatea cererilor.

În Python, cu biblioteca PyJWT și dependența ei criptografică, instalată cu pip install pyjwt[crypto] conform documentației ei. În terminalul de pe Mac, pune ghilimele: pip install "pyjwt[crypto]", altfel zsh refuză parantezele pătrate.

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)

Apoi îl trimiți în headerul Authorization, ca în exemplul Apple:

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

Am rulat scriptul pe 3 noiembrie 2026 cu o cheie de unică folosință generată pe mașina mea: headerul și conținutul tokenului corespund paginii Apple, iar semnătura ES256 se verifică. Nu l-am trimis la API-ul Apple cu această cheie de test, care nu există la Apple. Refolosește același token cât timp e valabil: Apple recomandă asta pentru performanțe mai bune.

Revocarea unei chei

Revocă o cheie imediat ce e pierdută, compromisă sau când un tool nu mai are nevoie de ea. Conform ajutorului App Store Connect, cu un cont Account Holder sau Admin:

1. Deschide Users and Access, apoi Integrations.
2. Alege Team Keys sau Individual Keys, apoi dă click pe Edit.
3. Bifează cheile de revocat, apoi Revoke Key.
4. Confirmă cu Revoke.

O cheie revocată nu se mai reactivează niciodată. Apple o afișează 30 de zile la Revoked. Fiecare tool care o folosea eșuează atunci la autentificare. Cu Expo, mesajul este „App Store Connect rejected the API authentication credentials”. Mesajul ăsta și celelalte eșecuri de trimitere sunt explicate în erorile de trimitere cu EAS și rezolvarea lor. Dacă cheia nu e compromisă, pregătește-o pe cea nouă înainte s-o oprești pe cea veche. Dacă e compromisă, Apple cere s-o revoci imediat.

Pentru propria ta cheie individuală: profilul tău, Individual API Key, apoi Revoke.

Checklistul meu pentru cheia .p8

• Account Holder a cerut acces la API.
• Cheia e o cheie de echipă dacă servește pentru build-uri sau profiluri.
• Rolul ei e cel mai mic care acoperă utilizarea, iar numele spune ce tool o folosește.
• .p8-ul e ținut în afara repository-ului, cu permisiuni stricte și o copie de rezervă criptată.
• Issuer ID și Key ID sunt notate separat, fără fișier.
• Fiecare tool are cheia lui, ca să poți revoca doar una.

Automatizează-ți publicarea fără să-ți lași cheia la vedere

Cheia e doar o piesă din traseu. iOS & Android Kit pornește de la codul de bază al aplicațiilor mele, cu abonamente incluse, și te duce în patru etape până în App Store, în ritmul tău. Dacă conectezi RevenueCat cu această cheie, configurarea completă e în RevenueCat și abonamentul in-app iOS.

Dacă îți pregătești prima lansare, fă-ți diagnosticul gratuit: îți spune ce te blochează cu adevărat și îți trimite checklistul meu anti-respingere Apple. Pagina publicarea unei aplicații în App Store reia fiecare etapă, de la pagina din store până la aprobare.

Întrebări frecvente

Cum creez o cheie API App Store Connect?

Account Holder cere mai întâi acces la API. Apoi un Admin deschide Users and Access, tabul Integrations, App Store Connect API, Team Keys. Dă click pe Generate API Key, alege un nume și un rol, generează cheia, apoi descarcă fișierul .p8.

Pot descărca din nou o cheie .p8 pierdută?

Nu. Fișierul se descarcă o singură dată, iar Apple nu păstrează nicio copie. Revocă cheia pierdută, generează una nouă și actualizează fiecare tool care o folosea.

Unde găsesc Issuer ID și Key ID?

În App Store Connect, meniul Users and Access, tabul Integrations. Issuer ID apare în partea de sus a paginii. Key ID se află în lista cheilor active. O cheie individuală nu folosește Issuer ID.

Ce rol să dau unei chei folosite de Expo?

Ghidul Expo dă rolul Admin. Conform tabelului de roluri Apple, App Manager e suficient pentru a trimite build-uri și a crea certificate și profiluri. Ăsta e rolul cheii mele, folosită pentru build-urile Expo.

Pot schimba rolul unei chei API?

Nu. Apple nu permite modificarea numelui sau a rolului unei chei după creare. Revoc-o, apoi generează una nouă cu rolul potrivit.

Expiră o cheie API App Store Connect?

Paginile Apple nu menționează nicio expirare a cheii, doar revocarea ei. Tokenurile semnate cu ea sunt cele care expiră, după cel mult 20 de minute pentru majoritatea cererilor.