Apple Wallet passes
that actually update

There is a lot of material on generating a .pkpass file. There is almost none on the part that matters: keeping it current. A loyalty card that shows a stale stamp count, an event ticket that cannot be moved to a new gate, a membership that cannot be revoked — these are the same failure, and it is a failure of infrastructure, not of design.

This guide covers the complete update path. It is written from the implementation that runs Labs Loyalty's own Wallet cards in production — signing, the web service, and push are all live there — and it deliberately spends most of its length on the three things that actually break: the web service contract, APNs over mutual-TLS, and a handful of undocumented behaviours that will cost you days if you meet them cold.

1. What a pass actually is

A .pkpass is a ZIP archive. Inside it:

• pass.json — the content and structure
• images — icon.png, logo.png, and type-specific art such as strip.png, each at 1x/2x/3x
• manifest.json — a SHA-1 of every other file in the archive
• signature — a detached PKCS#7 signature over that manifest

The signature is what makes it a pass rather than a zip. Change one byte of any file without re-signing and the device rejects it silently.

The five pass types

boardingPass, coupon, eventTicket, storeCard, generic. The type determines the layout and which image slots exist. You cannot invent one, and you cannot change a pass's type after issue.

2. Signing

You need three things from Apple: a Pass Type ID, a signing certificate for it, and the Apple WWDR intermediate certificate. The signature chains your certificate to Apple's root.

To make a pass updatable, pass.json must carry two extra keys:

{
  // ... your normal pass content ...
  "webServiceURL": "https://api.example.com",
  "authenticationToken": "<per-pass secret, 16+ chars>"
}

Two secrets are involved, not one, and they cover different calls. authenticationToken is the bearer credential above, sent as Authorization: ApplePass <token> on register, unregister and fetch-pass. The device's own deviceLibraryIdentifier — not a secret, just an opaque per-device id you chose when it registered — is what the "what changed?" endpoint below is keyed on. Treat the auth token as a real bearer credential: generate it randomly per pass, store its hash, and never reuse one across passes.

3. The web service

Once webServiceURL is present, the device starts talking to you. Five endpoints, and Apple's spec is exact about all of them. {deviceId} below is shorthand — the real path segment is deviceLibraryIdentifier, which is what you'll see in the actual spec and in any library's route table.

Two behaviours worth knowing before you go looking for bugs:

• The device calls GET /v1/passes/... a few seconds after every install, unprompted. That is not a bug and not a push — it is the device confirming it has the current version.
• Return 204 No Content from the updates check when nothing changed — Apple's current docs define this explicitly as "No Matching Passes," so this is spec, not folklore. Returning 200 with an empty list instead is a documented cause of some iOS versions re-fetching every pass unnecessarily. (Tested against recent iOS only — older versions reportedly logged their own complaints about a bare 204, so don't assume this is universally silent across every iOS release still in the wild.)

4. The push channel — the part that breaks

This is where implementations die. Wallet push does not use a normal APNs auth key. It authenticates with your pass certificate as a TLS client certificate — mutual TLS, against api.push.apple.com.

The payload is empty. The apns-topic is your Pass Type ID, not a bundle ID. The push type is background.

// Deno — mutual-TLS client cert on the fetch client
const client = Deno.createHttpClient({
  cert: signerCertPem,   // your pass certificate, PEM
  key:  signerKeyPem,    // its private key, PEM
});

await fetch(`https://api.push.apple.com/3/device/${pushToken}`, {
  method: "POST",
  client,
  headers: {
    "apns-topic": PASS_TYPE_ID,      // NOT a bundle id
    "apns-push-type": "background",
    "apns-priority": "5",            // required: default (10) + background is a documented APNs error
  },
  body: "{}",                         // deliberately empty
});

Don't skip apns-priority: 5. APNs' default priority is 10, and 10 paired with a background push type is a documented rejection — the frustrating version of this bug returns a plain 200 from APNs while the device does nothing at all, so it looks like your push worked right up until you check whether the pass actually updated.

The full update sequence

1. Your data changes.
2. You look up every registration for that pass serial.
3. You send an empty push to each device token.
4. The device calls your passesUpdatedSince endpoint.
5. You answer with the changed serials.
6. The device fetches each pass fresh.
7. You sign a new .pkpass at request time and return it.

Note step 7. You are not storing pass files and serving them — you are regenerating and re-signing on demand. Build your pass generation as a pure function of your data from the very beginning, or you will rewrite it later.

5. Gotchas worth the time they cost

Serve the right content type

application/vnd.apple.pkpass. Get it wrong and the device downloads a zip instead of offering to add a pass.

Images are not optional

A missing icon.png produces a pass that fails to install with no error message. The icon is what appears in notifications and the lock screen, so it is required even though nothing tells you so.

Test on a real device

The Simulator's Wallet behaviour diverges from a real phone, particularly around registration and push. A pass that installs and updates in the Simulator proves very little.

Verify by unzipping, not by trusting

Pull a real signed pass from your live endpoint, unzip it, and read pass.json and the image bytes. A 200 response tells you your server worked; it tells you nothing about whether the pass is correct. This is how the footerFields problem above gets found.

Gateway auth in front of your functions

If your web service sits behind a platform that verifies its own auth tokens by default, Apple's calls will be rejected before your code runs — Apple sends Authorization: ApplePass <token>, which is not your platform's scheme. You will see a gateway 401 and no logs at all. Deploy these endpoints with platform auth disabled and do the ApplePass check yourself.

6. The certificate question, before you build a business on it

If you are issuing passes for other people, the constraint is not technical. Apple's position is that the entity owning the certificate should be the entity issuing and redeeming the passes. Issuing on a client's behalf means holding a written agreement authorising it, and putting a clear disclaimer on the back of the pass stating you are authorised and where it can be redeemed. Apple can revoke certificates for violations.

Do not confuse this with certificate expiry above — they are different failure modes with very different blast radii. Expiry is the soft case: installed passes keep showing whatever they last displayed, you simply lose the ability to sign new passes or push updates until you renew. Revocation is not the same thing with a different name. Apple's own certificate documentation is explicit about it: once a certificate is revoked, passes signed with it "will no longer function properly" — not "stop updating," stop functioning. A revocation can break passes that are already sitting on someone's lock screen, not just freeze them in place. If you are issuing passes for other people, write the revocation risk into your terms as a real, hard failure — not the same soft "it'll just go stale" degradation the certificate-expiry callout above describes.