Clau API d'App Store Connect (.p8): crear-la i fer-la servir

Una clau API d'App Store Connect permet que una eina, com EAS, fastlane, RevenueCat o el teu propi script, actuï sobre el teu compte sense la teva contrasenya ni la doble autenticació. Apple es queda la meitat pública de la clau, i tu descarregues la meitat privada, un fitxer .p8, un sol cop. Amb aquest fitxer, l'Issuer ID i el Key ID, signes tokens vàlids durant 20 minuts com a màxim per a la majoria de peticions.

Publico les meves apps iOS, entre elles TradaZen i Nolera, amb Expo. Una clau d'equip amb el rol App Manager em serveix per a RevenueCat, per als builds d'Expo i per a una eina de línia d'ordres que edita les meves fitxes. Aquesta guia segueix les pàgines d'Apple, d'Expo i de fastlane revisades el 3 de novembre de 2026. No la confonguis amb les claus de serveis que es posen dins el codi d'una app: aquestes les trobaràs a clau API secreta en una app Expo.

Què fa una clau API d'App Store Connect

Segons la documentació d'Apple, l'API d'App Store Connect exigeix un token JWT per a cada petició. El generes i el signes amb la teva clau privada. La clau només serveix per a aquesta API: no la pots fer servir per a altres serveis d'Apple.

El seu avantatge cap en una frase: cap persona ha de validar la connexió. El teu identificador d'Apple topa amb la doble autenticació, i això bloqueja qualsevol automatització. La guia EAS Submit iOS mostra què canvia per a l'enviament d'una app Expo.

Abans de res: demanar accés a l'API

La primera clau no es pot crear d'entrada. L'ajuda d'App Store Connect ho deixa clar: l'Account Holder ha de demanar primer l'accés a l'API. Obre Users and Access, fa clic a Integrations i després a Request Access. Apple revisa la sol·licitud cas per cas.

L'Account Holder és la persona que va registrar el compte. Si comences, ets tu: la guia compte de desenvolupador d'Apple detalla el registre.

Clau d'equip o clau individual

Apple ofereix dos tipus de claus. Aquestes són les diferències, extretes de la documentació i de l'ajuda d'App Store Connect:

Criteri	Clau d'equip	Clau individual
Qui la pot generar	Account Holder o Admin	Gairebé qualsevol usuari
Apps accessibles	Totes, sense excepció	Les de l'usuari
Permisos	El rol escollit	Els de l'usuari
Nombre de claus	Diverses	Una d'activa per persona
Certificats i perfils	Sí, segons el rol	No
Vendes, finances, notaryTool	Segons el rol	No
Camp del token	iss = Issuer ID	sub = user

"Gairebé qualsevol usuari" vol dir, segons Apple: Account Holder, Admin, App Manager, Customer Support, Developer i Marketing, tret que un Admin o l'Account Holder els hagi tret el permís de generar una clau individual.

Per a Expo o fastlane, tria una clau d'equip. Una clau individual no té accés als endpoints d'aprovisionament, els que creen certificats i perfils. La documentació de fastlane ho confirma: les claus d'equip són obligatòries per a qualsevol accés relacionat amb l'aprovisionament.

Quin rol donar a la clau

Una clau d'equip accedeix a totes les apps del compte, sigui quin sigui el rol. El rol decideix què pot fer. Apple avisa que una clau Admin pot crear i eliminar usuaris: dona el rol més petit que cobreixi el teu ús. Els permisos de sota surten de la taula de rols d'Apple.

Ús de la clau	Rols que ho permeten
Enviar builds	Admin, App Manager, Developer
Gestionar els builds de TestFlight	Admin, App Manager
Crear certificats i perfils	Admin, App Manager
Enviar una app a revisió	Admin, App Manager
Importar productes i preus (RevenueCat)	App Manager com a mínim
Generar altres claus d'equip	Admin

La fila de RevenueCat surt de la seva documentació. La guia d'Expo, en canvi, dona el rol Admin a la clau. A les meves apps, el rol App Manager n'hi ha prou: EAS hi crea els perfils de distribució, i RevenueCat hi importa els productes.

Un cop generada la clau, ja no en pots modificar ni el nom ni el rol. Per canviar-los, cal revocar-la i generar-ne una altra.

Crear una clau d'equip, pas a pas

Necessites un compte Admin o Account Holder. Segons Apple:

1. Obre Users and Access i després la pestanya Integrations.
2. Tria App Store Connect API a la columna de l'esquerra i després la pestanya Team Keys.
3. Fes clic a Generate API Key, o al botó +.
4. Posa un nom a la clau. Només et serveix a tu, no forma part de la clau. Posa-li el nom de l'eina que la farà servir.
5. Tria el rol a Access i fes clic a Generate.
6. Descarrega la clau privada amb l'enllaç Download API Key.

L'enllaç de descàrrega desapareix tan bon punt has descarregat el fitxer, i Apple no en guarda cap còpia. Desa el .p8 abans de tancar la pàgina.

Després apunta els dos identificadors. Segons la pàgina d'Apple sobre els tokens, l'Issuer ID es mostra a la part de dalt de la pàgina Integrations, amb un botó Copy. El Key ID apareix a la llista de claus actives: passa-hi el ratolí per sobre perquè aparegui Copy Key ID. L'Issuer ID és el mateix per a totes les claus d'equip del compte. El Key ID és propi de cada clau.

Per a una clau individual és més curt: obre el teu perfil d'usuari, baixa fins a Individual API Key i fes clic a Generate API Key. La descàrrega també és única.

Desar el fitxer .p8

Apple demana que tractis la clau com una contrasenya: no la comparteixis, no la desis en un repositori de codi i no la posis mai dins el codi d'una app. La meva rutina:

• Una carpeta fora del projecte, o el gestor de secrets de la teva eina d'integració contínua.
• La carpeta de les claus al teu .gitignore, si el fitxer ha de viure al projecte mentre dura un enviament.
• Permisos estrictes. Una eina de línia d'ordres per a App Store Connect em rebutjava el .p8 mentre el fitxer era llegible per altres comptes. Un chmod 600 ho va solucionar.
• Una clau per eina. Apple permet generar diverses claus, amb els rols que vulguis.

Aquest últim punt no el vaig aplicar al principi. La meva clau App Manager serveix alhora per a RevenueCat, per als builds i per a l'eina de fitxes. Si l'he de revocar, cauen tres eines de cop. Si ho tornés a fer, crearia una clau per eina, per poder-ne tallar una sense tocar les altres.

Fer-la servir amb Expo

Tres maneres de donar la clau a EAS:

• Deixar que EAS la gestioni. eas credentials --platform ios pot crear una clau i guardar-la als servidors d'Expo. És el camí més senzill.
• Declarar-la a eas.json. El perfil submit accepta ascApiKeyPath, ascApiKeyIssuerId i ascApiKeyId. Segons la referència d'eas.json, aquests camps accepten variables d'entorn, com $ASC_API_KEY_PATH.
• Passar-la per l'entorn. El repositori d'EAS CLI documenta EXPO_ASC_API_KEY_PATH, EXPO_ASC_KEY_ID i EXPO_ASC_ISSUER_ID. Per a una clau individual, s'omet l'Issuer ID.

Un límit que cal conèixer per als builds: Expo explica que l'API oficial no sap vincular un App Group, un Merchant ID o un contenidor de CloudKit. Llavors cal una connexió amb el teu identificador d'Apple, en local. M'ha passat amb Nolera i el grup d'apps del seu widget: la clau activava la capacitat, però no vinculava el grup. Vaig fer la vinculació al portal de desenvolupadors d'Apple. Si la sincronització de capacitats es bloqueja, EXPO_NO_CAPABILITY_SYNC=1 la desactiva, i actives tu mateix la capacitat a l'identificador de l'app. La signatura dels builds està detallada a certificat i provisioning profile iOS.

Fer-la servir amb fastlane

fastlane llegeix la clau des d'un fitxer JSON. Els camps key_id, issuer_id i key, el contingut del .p8, són obligatoris. duration i in_house són opcionals. Valors d'exemple:

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

Després passes aquest fitxer a una acció, per exemple fastlane pilot distribute --api_key_path fastlane/cle.json. En un Fastfile, l'acció app_store_connect_api_key rep key_id, issuer_id i key_filepath. La durada de la sessió no passa de 1.200 segons, és a dir, 20 minuts. No totes les accions ho admeten: fastlane avisa, per exemple, que produce i pem no funcionen amb una clau API.

Fer-la servir al teu propi script

Sense eina, el token el fabriques tu. Apple en fixa la recepta:

• Capçalera: alg val ES256, kid val el teu Key ID, typ val JWT.
• Contingut, clau d'equip: iss, el teu Issuer ID; iat, l'hora de creació; exp, l'hora de caducitat; aud, que val appstoreconnect-v1.
• Contingut, clau individual: sub val user en lloc de iss.
• Durada: per sobre de 20 minuts, Apple rebutja el token per a la majoria de peticions.

En Python, amb la biblioteca PyJWT i la seva dependència criptogràfica, instal·lada amb pip install pyjwt[crypto] segons la seva documentació. Al terminal del Mac, posa-hi cometes: pip install "pyjwt[crypto]", si no zsh rebutja els claudàtors.

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)

Després l'envies a la capçalera Authorization, com a l'exemple d'Apple:

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

Vaig executar aquest script el 3 de novembre de 2026 amb una clau d'un sol ús generada a la meva màquina: la capçalera i el contingut del token coincideixen amb la pàgina d'Apple, i la signatura ES256 es verifica. No l'he enviat a l'API d'Apple amb aquesta clau de prova, que no existeix a Apple. Reutilitza el mateix token mentre sigui vàlid: Apple ho recomana per tenir millor rendiment.

Revocar una clau

Revoca una clau tan bon punt es perdi, quedi compromesa o una eina ja no la faci servir. Segons l'ajuda d'App Store Connect, amb un compte Account Holder o Admin:

1. Obre Users and Access i després Integrations.
2. Tria Team Keys, o Individual Keys, i fes clic a Edit.
3. Marca les claus que vols revocar i després Revoke Key.
4. Confirma amb Revoke.

Una clau revocada no es reactiva mai. Apple la mostra 30 dies a Revoked. Totes les eines que la feien servir fallen llavors a l'autenticació. Amb Expo, el missatge és "App Store Connect rejected the API authentication credentials". Aquest missatge i els altres errors d'enviament s'expliquen a els errors d'enviament amb EAS i com corregir-los. Si la clau no està compromesa, prepara la nova abans de tallar l'antiga. Si ho està, Apple demana revocar-la immediatament.

Per a la teva pròpia clau individual: el teu perfil, Individual API Key i després Revoke.

La meva checklist de la clau .p8

• L'Account Holder ha demanat accés a l'API.
• La clau és d'equip si serveix per als builds o els perfils.
• El seu rol és el més petit que cobreix l'ús, i el seu nom diu quina eina la fa servir.
• El .p8 està desat fora del repositori, amb permisos estrictes i una còpia de seguretat xifrada.
• L'Issuer ID i el Key ID estan apuntats a banda, sense el fitxer.
• Cada eina té la seva clau, per poder-ne revocar només una.

Automatitzar la publicació sense deixar-hi la clau

La clau només és una peça del recorregut. L'iOS & Android Kit parteix del codi base de les meves apps, subscripcions incloses, i segueix quatre etapes fins a l'App Store, al teu ritme. Si connectes RevenueCat amb aquesta clau, el muntatge complet és a RevenueCat i la subscripció in-app a iOS.

Si prepares el teu primer llançament, fes el diagnòstic gratuït: et diu què et bloqueja de veritat i t'envia la meva checklist antirebuig d'Apple. La pàgina publicar una aplicació a l'App Store repassa cada etapa, de la fitxa a l'aprovació.

Preguntes freqüents

Com es crea una clau API d'App Store Connect?

Primer, l'Account Holder demana accés a l'API. Després, un Admin obre Users and Access, pestanya Integrations, App Store Connect API, Team Keys. Fa clic a Generate API Key, tria un nom i un rol, genera la clau i descarrega el fitxer .p8.

Es pot tornar a descarregar una clau .p8 perduda?

No. El fitxer es descarrega un sol cop, i Apple no en guarda cap còpia. Revoca la clau perduda, genera'n una de nova i actualitza totes les eines que la feien servir.

On trobo l'Issuer ID i el Key ID?

A App Store Connect, menú Users and Access, pestanya Integrations. L'Issuer ID es mostra a la part de dalt de la pàgina. El Key ID surt a la llista de claus actives. Una clau individual no fa servir Issuer ID.

Quin rol cal donar a una clau que fa servir Expo?

La guia d'Expo dona el rol Admin. Segons la taula de rols d'Apple, App Manager n'hi ha prou per enviar builds i crear certificats i perfils. És el rol de la meva clau, que faig servir per als builds d'Expo.

Es pot canviar el rol d'una clau API?

No. Apple no permet modificar ni el nom ni el rol d'una clau després de crear-la. Revoca-la i genera'n una de nova amb el rol correcte.

Caduca una clau API d'App Store Connect?

Les pàgines d'Apple no esmenten cap caducitat de la clau, només la revocació. Els que caduquen són els tokens signats amb ella, al cap de 20 minuts com a màxim per a la majoria de peticions.