Overview: Why Apple Pass Type ID Certificates Are Required
Apple mandates that every production .pkpass archive be cryptographically signed using a Pass Type ID Certificate issued under your organization's Apple Developer Program account (Certificate Management API at /api/v1/certificates). The certificate serves two critical functions:
-
1
Detached PKCS#7 Bundle Signing: Signs
manifest.jsoninside every.pkpassarchive (chaining to Apple's WWDR G4/G6 intermediate certificate) so iOS verifies authenticity and displays your verified Organization Name. -
2
APNs HTTP/2 Push Authentication: Authenticates TLS HTTP/2 connections to
api.push.apple.comunder the certificate'spass.com.<domain>.<name>topic so Passinstance can wake customer iPhones for live pass updates.
Prerequisites: You need an active Apple Developer Program membership (
Account HolderorAdminrole) to register Pass Type IDs and issue production Pass Type ID certificates. While Passinstance provides a managed sandbox certificate for initial onboarding demos, you must bind your own Pass Type ID certificate before distributing production passes to customers — Apple does not allow migrating already-installed passes to a differentpassTypeIdentifierorteamIdentifierafter installation.
Step-by-Step Certificate Setup Workflow
-
1
Generate a CSR in Passinstance: Navigate to Settings -> Wallet -> Apple Certificates (
/settings/workspace/wallet) and click Generate CSR (callsPOST /api/v1/certificates/generate-csrwith optionalpassTypeId). Download the.certSigningRequestfile. Passinstance stores the generated RSA private key (CertificatePkey) in encrypted storage. -
2
Register a Pass Type ID in Apple Developer: Sign in to Apple Developer Portal -> Certificates, Identifiers & Profiles -> Identifiers, click +, select Pass Type IDs, and register a reverse-DNS identifier such as
pass.com.yourbrand.loyalty. -
3
Issue the Signed
.cerin Apple Developer: Open your new Pass Type ID, click Create Certificate, upload the.certSigningRequestfile downloaded from Passinstance, and download the resultingpass.cerfile. -
4
Upload
pass.certo Passinstance: Uploadpass.cerviaPOST /api/v1/certificates(multipart/form-data, optionalteamIdentifier,passTypeId,demo,isNfcCertificate) orPOST /api/v1/certificates/upsert(file+type: "TYPE_PASS" | "TYPE_NFC"). Passinstance links the.cerwith the generated private key, verifies the Apple WWDR G4/G6 intermediate chain, and packages the encrypted.p12signing bundle. -
5
Bind Certificate to Your Template: Open Template Settings and bind your verified Pass Type ID certificate.
Certificate Management API Reference (Certificate Management API)
| Method | Endpoint Path | Permission Required | Description | |
|---|---|---|---|---|
| POST | /api/v1/certificates/generate-csr | certificates:manage | Generates an RSA key pair (CertificatePkey) and returns a PEM Certificate Signing Request (.csr). | |
| POST | /api/v1/certificates | certificates:manage | Uploads an Apple-signed .cer file via multipart/form-data, verifies WWDR G4/G6 trust, and activates the certificate (CertificateType: `TYPE_PASS \ | TYPE_NFC`). |
| POST | /api/v1/certificates/upsert | certificates:manage | Creates or updates/renews an existing certificate from a signed .cer (multipart/form-data, optional pkeyId, type, intermediatePem). | |
| GET | /api/v1/certificates | certificates:read | Lists workspace certificates with passTypeIdentifier, teamIdentifier, validFrom, validTo, and status. | |
| GET | /api/v1/certificates/:id | certificates:read | Returns X.509 metadata and details for a specific certificate ID. | |
| DELETE | /api/v1/certificates/:id | certificates:manage | Removes an unused or expired certificate. |
Example: Generating a CSR & Uploading pass.cer
1. Generate CSR (POST /api/v1/certificates/generate-csr):
POST /api/v1/certificates/generate-csr
{
"passTypeId": "pass.com.phenixroasters.loyalty"
}
Response (200 OK):
{
"success": true,
"data": {
"csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIICvDCCAaQCAQAwdzELMAkGA1UEBhMCREUx...\n-----END CERTIFICATE REQUEST-----"
},
"description": "CSR generated successfully",
"errors": [],
"statusCode": 200
}
2. Upload Signed .cer (POST /api/v1/certificates):
Submit as multipart/form-data with field file (pass.cer), optional passTypeId, teamIdentifier, and isNfcCertificate ("false" or "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"
Response (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"
}
See Certificate Renewal & Management and Apple Wallet for lifecycle maintenance.
