Panoramica: perché sono necessari i certificati Apple Pass Type ID
Apple impone che ogni archivio .pkpass di produzione sia firmato crittograficamente mediante un Certificato Pass Type ID emesso sotto l'account Apple Developer Program dell'organizzazione (Certificate Management API su /api/v1/certificates). Il certificato svolge due funzioni critiche:
-
1
Firma detached PKCS#7 del bundle: Firma
manifest.jsonall'interno di ogni archivio.pkpass(collegandosi al certificato intermedio Apple WWDR G4/G6) in modo che iOS verifichi l'autenticità e mostri il nome verificato dell'organizzazione. -
2
Autenticazione push HTTP/2 APNs: Autentica le connessioni TLS HTTP/2 verso
api.push.apple.comsotto il topicpass.com.<domain>.<name>del certificato, consentendo a Passinstance di risvegliare gli iPhone dei clienti per aggiornamenti live dei pass.
Prerequisiti: È necessario un abbonamento attivo ad Apple Developer Program (ruolo
Account HolderoAdmin) per registrare Pass Type ID ed emettere certificati Pass Type ID di produzione. Sebbene Passinstance fornisca un certificato sandbox gestito per le demo iniziali dell'onboarding, è indispensabile associare il proprio certificato Pass Type ID prima di distribuire pass di produzione ai clienti — Apple non consente di migrare pass già installati a un diversopassTypeIdentifieroteamIdentifierdopo l'installazione.
Procedura passo per passo di configurazione del certificato
-
1
Generazione del CSR in Passinstance: Acceda a Impostazioni -> Wallet -> Certificati Apple (
/settings/workspace/wallet) e clicchi su Genera CSR (richiamaPOST /api/v1/certificates/generate-csrconpassTypeIdopzionale). Scarichi il file.certSigningRequest. Passinstance archivia la chiave privata RSA generata (CertificatePkey) in uno storage cifrato. -
2
Registrazione di un Pass Type ID in Apple Developer: Acceda a Apple Developer Portal -> Certificates, Identifiers & Profiles -> Identifiers, clicchi su +, selezioni Pass Type IDs e registri un identificativo in formato DNS inverso come
pass.com.yourbrand.loyalty. -
3
Emissione del file
.cerfirmato in Apple Developer: Apra il nuovo Pass Type ID, clicchi su Create Certificate, carichi il file.certSigningRequestscaricato da Passinstance e scarichi il filepass.cerrisultante. -
4
Caricamento di
pass.cerin Passinstance: Carichipass.certramitePOST /api/v1/certificates(multipart/form-data, parametri opzionaliteamIdentifier,passTypeId,demo,isNfcCertificate) oppurePOST /api/v1/certificates/upsert(file+type: "TYPE_PASS" | "TYPE_NFC"). Passinstance collega il file.ceralla chiave privata generata, verifica la catena intermedia Apple WWDR G4/G6 e prepara il bundle di firma cifrato.p12. -
5
Associazione del certificato al modello: Apra le Impostazioni del modello e associ il proprio certificato Pass Type ID verificato.
Riferimento API per la gestione certificati (Certificate Management API)
| Metodo | Percorso endpoint | Permesso richiesto | Descrizione | |
|---|---|---|---|---|
| POST | /api/v1/certificates/generate-csr | certificates:manage | Genera una coppia di chiavi RSA (CertificatePkey) e restituisce una Certificate Signing Request PEM (.csr). | |
| POST | /api/v1/certificates | certificates:manage | Carica un file .cer firmato da Apple tramite multipart/form-data, verifica la catena WWDR G4/G6 e attiva il certificato (CertificateType: `TYPE_PASS \ | TYPE_NFC`). |
| POST | /api/v1/certificates/upsert | certificates:manage | Crea o aggiorna/rinnova un certificato esistente da un .cer firmato (multipart/form-data, opzionali pkeyId, type, intermediatePem). | |
| GET | /api/v1/certificates | certificates:read | Elenca i certificati del workspace con passTypeIdentifier, teamIdentifier, validFrom, validTo e stato. | |
| GET | /api/v1/certificates/:id | certificates:read | Restituisce i metadati X.509 e i dettagli per uno specifico ID certificato. | |
| DELETE | /api/v1/certificates/:id | certificates:manage | Rimuove un certificato non utilizzato o scaduto. |
Esempio: generare un CSR e caricare pass.cer
1. Genera CSR (POST /api/v1/certificates/generate-csr):
POST /api/v1/certificates/generate-csr
{
"passTypeId": "pass.com.phenixroasters.loyalty"
}
Risposta (200 OK):
{
"success": true,
"data": {
"csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIICvDCCAaQCAQAwdzELMAkGA1UEBhMCREUx...\n-----END CERTIFICATE REQUEST-----"
},
"description": "CSR generated successfully",
"errors": [],
"statusCode": 200
}
2. Carica .cer firmato (POST /api/v1/certificates):
Invii come multipart/form-data con campo file (pass.cer), oltre ai campi opzionali passTypeId, teamIdentifier e isNfcCertificate ("false" o "true"):
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"
Risposta (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"
}
Consulti Rinnovo e gestione dei certificati e Apple Wallet per la manutenzione del ciclo di vita.
