Overview: Why Certificate Expiry Monitoring Matters
Apple Pass Type ID certificates (pass.com.yourbrand.*) have a strict validity period of 397 days (~13 months) enforced by Apple's Certification Authority. If a certificate is allowed to expire without renewal:
-
New Downloads Fail: Passinstance cannot generate valid detached PKCS#7 signatures for new
.pkpassdownloads bound to that certificate. -
APNs Push Updates Halt: Apple's HTTP/2 APNs gateway (
api.push.apple.com) immediately rejects TLS connections authenticated with an expired certificate, halting live balance and field updates on installed iPhones.
Important: Always renew under the exact same Pass Type ID (
pass.com.yourbrand.*) and Apple Developer Team ID rather than creating a brand-new Pass Type ID. Because iOS binds installed passes to the(passTypeIdentifier, teamIdentifier)tuple, renewing the certificate on the same Pass Type ID allows every existing pass on customer iPhones and Apple Watches to continue receiving APNs push updates with zero customer re-installation.
Zero-Downtime Certificate Renewal Procedure
-
1
Monitor Expiry Windows (
Certificate Renewal Monitor): Passinstance runs a daily scheduled check at 02:00 scanning active certificates withvalidTowithin 30 days, emailing workspace owners/admins and surfacing warnings in Settings -> Wallet -> Apple Certificates. -
2
Generate a Renewal CSR: Open the expiring certificate in Passinstance and download a new CSR (
POST /api/v1/certificates/generate-csr). -
3
Issue New Certificate under Existing Pass Type ID: In the Apple Developer Portal -> Identifiers -> Pass Type IDs, select your existing Pass Type ID, click Create Certificate, upload the CSR, and download the new
pass.cer. (Apple allows overlapping active certificates per Pass Type ID so you can rotate safely before revoking the old certificate.) -
4
Upsert Renewed
pass.cerin Passinstance: Upload the signed.cerviaPOST /api/v1/certificates/upsert(multipart/form-data, specifyingpassTypeId,type: "TYPE_PASS" | "TYPE_NFC", and optionalpkeyId). Passinstance verifies the Apple WWDR G4/G6 chain and swaps the active signing certificate. -
5
Verify Signing & APNs Push: Issue a test pass (
POST /api/v1/passes) and dispatch a push notification (POST /api/v1/push-notifications/passes/:id) to confirm both PKCS#7 bundle signing and APNs HTTP/2 delivery succeed.
Certificate Renewal & Lifecycle API Endpoints (Certificate Management API)
| Method | Endpoint Path | Permission Required | Description |
|---|---|---|---|
| GET | /api/v1/certificates | certificates:read | Lists workspace certificates and inspection metadata (validFrom, validTo, passTypeIdentifier, teamIdentifier, type). |
| POST | /api/v1/certificates/generate-csr | certificates:manage | Generates an RSA key pair (CertificatePkey) and returns a PEM CSR for signing in Apple Developer. |
| POST | /api/v1/certificates/upsert | certificates:manage | Creates or atomically replaces/renews an existing certificate from an uploaded signed .cer (multipart/form-data). |
| GET | /api/v1/certificates/:id | certificates:read | Inspects X.509 certificate metadata, validity dates, and Pass Type ID binding. |
| DELETE | /api/v1/certificates/:id | certificates:manage | Removes a superseded or unused certificate record. |
Example: Upserting a Renewed .cer Bundle
curl -X POST https://api.passinstance.com/api/v1/certificates/upsert \
-H "X-API-Key: <API_KEY>" \
-F "file=@./pass-renewed.cer" \
-F "passTypeId=pass.com.phenixroasters.loyalty" \
-F "type=TYPE_PASS"
Response (201 Created / 200 OK):
{
"id": "cert_8841a9b0-2c3d-4e5f-8a9b-0c1d2e3f4a5b",
"passTypeIdentifier": "pass.com.phenixroasters.loyalty",
"teamIdentifier": "9A8B7C6D5E",
"type": "TYPE_PASS",
"validTo": "2027-12-31T23:59:59.000Z"
}
Apple WWDR G4 & G6 Intermediate Rollover
Passinstance manages Apple's Worldwide Developer Relations (WWDR) intermediate certificates (G4 and G6) automatically inside the server-side PKCS#7 certificate store (Apple Wallet Packager). You never need to manually upload AppleWWDRCAG4.cer or AppleWWDRCAG6.cer — Passinstance inspects the Authority Key Identifier (AKI) of your uploaded pass.cer and embeds the matching WWDR intermediate in every .pkpass signature.
See Apple Wallet Certificates and Apple Wallet for initial provisioning steps.
