Skip to main content

Simple VAPID header generation library

Project description

This minimal library contains the minimal set of functions you need to generate a VAPID key set and get the headers you’ll need to sign a WebPush subscription update.

VAPID is a voluntary standard for WebPush subscription providers (sites that send WebPush updates to remote customers) to self-identify to Push Servers (the servers that convey the push notifications).

The VAPID “claims” are a set of JSON keys and values. There are two required fields, one semi-optional and several optional additional fields.

At a minimum a VAPID claim set should look like:

{"sub":"mailto:YourEmail@YourSite.com","aud":"https://PushServer","exp":"ExpirationTimestamp"}

A few notes:

*sub* is the email address you wish to have on record for this request, prefixed with “mailto:”. If things go wrong, this is the email that will be used to contact you (for instance). This can be a general delivery address like “mailto:push_operations@example.com” or a specific address like “mailto:bob@example.com”.

*aud* is the audience for the VAPID. This is the scheme and host you use to send subscription endpoints and generally coincides with the endpoint specified in the Subscription Info block.

As example, if a WebPush subscription info contains: {"endpoint": "https://push.example.com:8012/v1/push/...", ...}

then the aud would be “https://push.example.com:8012

While some Push Services consider this an optional field, others may be stricter.

*exp* This is the UTC timestamp for when this VAPID request will expire. The maximum period is 24 hours. Setting a shorter period can prevent “replay” attacks. Setting a longer period allows you to reuse headers for multiple sends (e.g. if you’re sending hundreds of updates within an hour or so.) If no exp is included, one that will expire in 24 hours will be auto-generated for you.

Claims should be stored in a JSON compatible file. In the examples below, we’ve stored the claims into a file named claims.json.

py_vapid can either be installed as a library or used as a stand along app, bin/vapid.

App Installation

You’ll need python virtualenv Run that in the current directory.

Then run

bin/pip install -r requirements.txt

bin/python setup.py install

App Usage

Run by itself, bin/vapid will check and optionally create the public_key.pem and private_key.pem files.

bin/vapid -gen can be used to generate a new set of public and private key PEM files. These will overwrite the contents of private_key.pem and public_key.pem.

bin/vapid --sign claims.json will generate a set of HTTP headers from a JSON formatted claims file. A sample claims.json is included with this distribution.

bin/vapid --sign claims.json --json will output the headers in JSON format, which may be useful for other programs.

See bin/vapid -h for all options and commands.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for py-vapid, version 1.2.1
Filename, size File type Python version Upload date Hashes
Filename, size py-vapid-1.2.1.tar.gz (12.3 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page