Aperçu : pourquoi les certificats Pass Type ID Apple sont indispensables
Apple exige que toute archive .pkpass de production soit signée cryptographiquement par un certificat Pass Type ID émis depuis le compte Apple Developer Program de votre organisation (Certificate Management API sous /api/v1/certificates). Ce certificat assure deux fonctions critiques :
-
1
Signature PKCS#7 détachée du paquet : Signe
manifest.jsonà l'intérieur de chaque archive.pkpass(avec chaîne de confiance jusqu'au certificat intermédiaire Apple WWDR G4/G6) afin qu'iOS vérifie l'authenticité du passe et affiche le nom vérifié de votre organisation. -
2
Authentification push APNs HTTP/2 : Authentifie les connexions TLS HTTP/2 vers
api.push.apple.comsous le topicpass.com.<domain>.<name>du certificat, permettant à Passinstance de réveiller les iPhones clients lors des mises à jour en direct.
Prérequis : Vous devez disposer d'un abonnement Apple Developer Program actif (rôle
Account HolderouAdmin) pour créer des Pass Type IDs et générer vos certificats de production. Bien que Passinstance mette à disposition un certificat bac à sable géré pour vos premiers tests d'intégration, vous devez lier votre propre certificat Pass Type ID avant de distribuer des passes réels aux clients : Apple interdit de migrer des cartes déjà installées vers un autrepassTypeIdentifierouteamIdentifieraprès installation.
Workflow pas à pas de configuration du certificat
-
1
Générer une CSR dans Passinstance : Ouvrez Paramètres -> Wallet -> Certificats Apple (
/settings/workspace/wallet) et cliquez sur Générer une CSR (appellePOST /api/v1/certificates/generate-csravecpassTypeIdoptionnel). Téléchargez le fichier.certSigningRequest. Passinstance conserve en toute sécurité la clé privée RSA générée (CertificatePkey) dans son stockage chiffré. -
2
Enregistrer un Pass Type ID dans Apple Developer : Connectez-vous sur Apple Developer Portal -> Certificates, Identifiers & Profiles -> Identifiers, cliquez sur +, choisissez Pass Type IDs puis enregistrez un identifiant en notation DNS inversée tel que
pass.com.yourbrand.loyalty. -
3
Générer le certificat
.cersigné chez Apple : Ouvrez votre nouveau Pass Type ID, cliquez sur Create Certificate, importez le fichier.certSigningRequesttéléchargé depuis Passinstance, puis téléchargez le certificatpass.cerproduit. -
4
Importer
pass.cerdans Passinstance : Téléversezpass.cerviaPOST /api/v1/certificates(multipart/form-data, avecteamIdentifier,passTypeId,demoetisNfcCertificateoptionnels) ouPOST /api/v1/certificates/upsert(file+type: "TYPE_PASS" | "TYPE_NFC"). Passinstance associe le.cerà la clé privée générée, vérifie la chaîne intermédiaire Apple WWDR G4/G6 et génère le bundle.p12chiffré. -
5
Lier le certificat à votre modèle : Ouvrez les Paramètres du modèle et sélectionnez votre certificat Pass Type ID vérifié.
Référence API de gestion des certificats (Certificate Management API)
| Méthode | Chemin du point d'entrée | Permission requise | Description | |
|---|---|---|---|---|
| POST | /api/v1/certificates/generate-csr | certificates:manage | Génère une paire de clés RSA (CertificatePkey) et retourne une demande de signature de certificat PEM (.csr). | |
| POST | /api/v1/certificates | certificates:manage | Reçoit un fichier .cer signé par Apple en multipart/form-data, vérifie la chaîne WWDR G4/G6 et active le certificat (CertificateType : `TYPE_PASS \ | TYPE_NFC`). |
| POST | /api/v1/certificates/upsert | certificates:manage | Crée ou renouvelle un certificat existant depuis un .cer signé (multipart/form-data, options pkeyId, type, intermediatePem). | |
| GET | /api/v1/certificates | certificates:read | Liste les certificats de l'espace de travail avec passTypeIdentifier, teamIdentifier, validFrom, validTo et statut. | |
| GET | /api/v1/certificates/:id | certificates:read | Retourne les métadonnées X.509 détaillées d'un identifiant de certificat donné. | |
| DELETE | /api/v1/certificates/:id | certificates:manage | Supprime un certificat inutilisé ou expiré. |
Exemple : générer une CSR & importer pass.cer
1. Générer la CSR (POST /api/v1/certificates/generate-csr) :
POST /api/v1/certificates/generate-csr
{
"passTypeId": "pass.com.phenixroasters.loyalty"
}
Réponse (200 OK) :
{
"success": true,
"data": {
"csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIICvDCCAaQCAQAwdzELMAkGA1UEBhMCREUx...\n-----END CERTIFICATE REQUEST-----"
},
"description": "CSR generated successfully",
"errors": [],
"statusCode": 200
}
2. Importer le certificat signé pass.cer (POST /api/v1/certificates) :
Transmettez la requête en multipart/form-data avec le champ file (pass.cer), ainsi que passTypeId, teamIdentifier et isNfcCertificate ("false" ou "true") en option :
curl -X POST https://api.passinstance.com/api/v1/certificates \
-H "X-API-Key: <API_KEY>" \
-F "file=@./pass.cer" \
-F "passTypeId=pass.com.phenixroasters.loyalty" \
-F "isNfcCertificate=false"
Réponse (201 Created) :
{
"id": "cert_8841a9b0-2c3d-4e5f-8a9b-0c1d2e3f4a5b",
"passTypeIdentifier": "pass.com.phenixroasters.loyalty",
"teamIdentifier": "9A8B7C6D5E",
"type": "TYPE_PASS",
"validFrom": "2026-11-15T10:18:00.000Z",
"validTo": "2027-12-15T10:17:59.000Z"
}
Consultez Renouvellement & gestion des certificats et Apple Wallet pour la maintenance annuelle.
