Separate VAPID from payload encryption
VAPID and message encryption solve different problems. VAPID identifies the application server making a request to the push service. The Web Push payload-encryption guide explains the separate subscription key material that prevents the push service from reading message content.
Place each key in the correct environment
| Value | Where it belongs | Purpose |
|---|---|---|
| VAPID public key | Server configuration and browser subscription code | Passed as applicationServerKey and used to bind or identify the sender. |
| VAPID private key | Protected application-server secret storage only | Signs the authorization token sent to the push service. |
Subscription p256dh | Browser subscription record and protected server database | Participates in deriving encryption keys for that subscription. |
Subscription auth | Browser subscription record and protected server database | Adds per-subscription authentication material to key derivation. |
Generate and back up the key pair once per intended identity
Use a well-maintained Web Push library or cryptographic tool that generates the required P-256 key pair. Store the private key in a secret manager or equivalent protected configuration, and record which sites or tenants use it. Back it up under the same controls as other production credentials.
Do not regenerate a pair on every deploy. If subscriptions were created with one application-server public key, replacing it can prevent the new sender identity from using that population. Treat a lost or replaced VAPID private key as a migration incident, not a normal configuration refresh.
Subscribe with the correctly encoded public key
const subscription = await registration.pushManager.subscribe({
userVisibleOnly: true,
applicationServerKey: urlBase64ToUint8Array(VAPID_PUBLIC_KEY)
});
Many libraries expose the public key as URL-safe base64 while the browser API expects bytes. Use a tested conversion function and do not alter padding or characters by hand. If subscribe() fails, inspect permission, worker readiness, the exact key bytes, and whether an existing subscription was created under a different key.
Build the authorization token for the endpoint audience
RFC 8292 defines a signed token containing an audience derived from the push-service origin, an expiration time, and an optional subject that can give the push-service operator a contact URI such as a mailto: address or HTTPS URL. The token must be short-lived and signed with the VAPID private key. A Web Push library normally performs these details; configure it rather than implementing JWT and header formatting from memory.
The endpoint determines the audience. Do not assume every subscription uses the same push-service hostname. Generate authorization from the endpoint being contacted.
Design rotation before rotation is urgent
A safe plan keeps the old key available while existing subscriptions remain in use and introduces the new public key only for subscriptions the new private key can serve. In many deployments, that means maintaining key-version metadata and gradually asking browsers to create a new subscription. Test the exact behavior of your library and target push services before committing to a schedule.
If the private key may have been exposed, stop treating it as trustworthy. Investigate access, preserve evidence, replace secrets, and plan subscriber migration. Merely changing the public JavaScript constant does not repair existing records.
Use key-version and site boundaries in storage
Store a non-secret key identifier with each subscription so the send path selects the correct protected private key. The subscription lifecycle data model shows how that key version fits beside site ownership and endpoint state. Never log the private key or complete subscription credentials.
Diagnose common VAPID failures deliberately
- Subscription creation fails: verify public-key decoding, key curve, worker registration, and permission state.
- Send returns authentication failure: verify the private key matches the subscribed public key, the token audience matches the endpoint origin, and the clock is accurate.
- Only older subscribers fail: check whether a key change split the subscription population.
- One push service fails: inspect that service’s endpoint origin and required authorization formatting through your library.
Read the specification before changing the identity model
Compare any key-management change with the service's Web Push architecture, especially its per-origin credential and subscriber boundaries. A product configuration cannot override the application-server identity attached to a browser subscription.
RFC 8292, Voluntary Application Server Identification for Web Push, defines the VAPID authentication scheme, token claims, subscription restriction, and public-key format. The W3C Push API defines applicationServerKey in subscription behavior. For product integration boundaries, continue with the Web Push API documentation.