Skip to content
Help Center Guide · Certificates & Credentials
3 min readVerified 2026-11-16

Certificate Renewal & Management

Monitor certificate expiry dates and rotate expiring Apple Pass Type ID certificates cleanly without invalidating live customer passes.

In This Guide

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 .pkpass downloads 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.
SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
ZERO-DOWNTIME CERTIFICATE RENEWAL
STAGE 01 AUTOMATED EXPIRY MONITORING CRON (Certificate Renewal Monitor)
Daily job at 02:00 checks active certificates with validTo <= now + 30 days
Notifies workspace contacts to upload a renewed certificate before expiration
STAGE 02 STEP 1: GENERATE CSR FOR EXISTING PASS TYPE ID
POST/api/v1/certificates/generate-csr
Preserves exact passTypeIdentifier (pass.com.yourbrand.loyalty)
Preserves 10-character Apple teamIdentifier
STAGE 03 STEP 2: APPLE DEVELOPER PORTAL CERTIFICATE ROLLOVER
Open existing Pass Type IDCreate CertificateUpload Renewal CSR
Download renewed pass.cer (Do NOT revoke old cert until new cert is active)
STAGE 04 STEP 3: UPSERT / SWAP (POST/api/v1/certificates/upsert)
Validates matching passTypeIdentifier & teamIdentifier + WWDR G4/G6 chain
Replaces active .p12 signer in encrypted storage & keeps all installed iOS passes syncing

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. 1
    Monitor Expiry Windows (Certificate Renewal Monitor): Passinstance runs a daily scheduled check at 02:00 scanning active certificates with validTo within 30 days, emailing workspace owners/admins and surfacing warnings in Settings -> Wallet -> Apple Certificates.
  2. 2
    Generate a Renewal CSR: Open the expiring certificate in Passinstance and download a new CSR (POST /api/v1/certificates/generate-csr).
  3. 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. 4
    Upsert Renewed pass.cer in Passinstance: Upload the signed .cer via POST /api/v1/certificates/upsert (multipart/form-data, specifying passTypeId, type: "TYPE_PASS" | "TYPE_NFC", and optional pkeyId). Passinstance verifies the Apple WWDR G4/G6 chain and swaps the active signing certificate.
  5. 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)

MethodEndpoint PathPermission RequiredDescription
GET/api/v1/certificatescertificates:readLists workspace certificates and inspection metadata (validFrom, validTo, passTypeIdentifier, teamIdentifier, type).
POST/api/v1/certificates/generate-csrcertificates:manageGenerates an RSA key pair (CertificatePkey) and returns a PEM CSR for signing in Apple Developer.
POST/api/v1/certificates/upsertcertificates:manageCreates or atomically replaces/renews an existing certificate from an uploaded signed .cer (multipart/form-data).
GET/api/v1/certificates/:idcertificates:readInspects X.509 certificate metadata, validity dates, and Pass Type ID binding.
DELETE/api/v1/certificates/:idcertificates:manageRemoves a superseded or unused certificate record.

Example: Upserting a Renewed .cer Bundle

BASH
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):

JSON
{
  "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.

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.