All Collections
Distribute
SmartPass Links
Generating hashed SmartPass links
Generating hashed SmartPass links

How to generate hashed SmartPass links from within your application

Paul Tomes avatar
Written by Paul Tomes
Updated over a week ago

PassKit allows you to quickly and easily generate URLs (weblinks) to pass records that can include unique data, without having to use the PassKit API. 

In addition to not having to use the PassKit API to create unique pass links, you can generate as many SmartPass links without creating a pass record in the PassKit database. Therefore a SmartPass link won't count toward your pass volume subscription.  i.e. you can have millions of SmartPass links but not pay for millions of passes. Only when the user clicks on the link will PassKit create and issue the pass. 

You can generate these SmartPass links from a CSV, although for a production integration we recommend you automate and trigger from a record being created (in a CRM for example). The SmartPass link can then be distributed in a welcome email from your CRM / email Service provider.

All you need to generate a SmartPass link is the ability to generate a link with a base64 encoded JSON payload, and create a signature HMAC hash off the link to allow PassKit to verify the data integrity.

Below is a high level flow & sample instructions. 

Important:

Generating Hashed Smart Pass Links

1. Define JSON payload with the pass data:

The payload can contain the coupon / member, PII & meta data that needs to go into the pass record:

{
"person.surname": "Kosterman",
"person.forename": "Patrick",
"person.email": "patrick@passkit.com",
"person.displayName": "Patrick Kosterman",
"members.member.profileImage": "https://passkit.com/patrick.png"
}

2. Base64 URL encode minified JSON payload

For above sample data:

eyJwZXJzb24uc3VybmFtZSI6Iktvc3Rlcm1hbiIsInBlcnNvbi5mb3JlbmFtZSI6IlBhdHJpY2siLCJwZXJzb24uZW1haWwiOiJwYXRyaWNrQHBhc3NraXQuY29tIiwicGVyc29uLmRpc3BsYXlOYW1lIjoiUGF0cmljayBLb3N0ZXJtYW4iLCJtZW1iZXJzLm1lbWJlci5wcm9maWxlSW1hZ2UiOiJodHRwczogLy9wYXNza2l0LmNvbS9wYXRyaWNrLnBuZyJ9

The format of the link is as follows:

https://pub1.pskt.io/c/{programId or campaignId}?data={base64JsonPayload}&sig={signatureHash}

So for the sample data it looks like the following:

https://pub1.pskt.io/c/{projectId}?data=eyJwZXJzb24uc3VybmFtZSI6Iktvc3Rlcm1hbiIsInBlcnNvbi5mb3JlbmFtZSI6IlBhdHJpY2siLCJwZXJzb24uZW1haWwiOiJwYXRyaWNrQHBhc3NraXQuY29tIiwicGVyc29uLmRpc3BsYXlOYW1lIjoiUGF0cmljayBLb3N0ZXJtYW4iLCJtZW1iZXJzLm1lbWJlci5wcm9maWxlSW1hZ2UiOiJodHRwczogLy9wYXNza2l0LmNvbS9wYXRyaWNrLnBuZyJ9

The signature hash is appended in the next step.

Each PassKit project has a unique secret that is used for creating a signature HMAC hash of the link. We support the following cryptographic hash functions MD5, SHA1, SHA223, SHA256, SHA384 and SHA512 / SHA3.

For the above sample let's create a SHA256 HMAC of the sample link:

https://pub1.pskt.io/c/{programId or campaignId}?data={base64JsonPayload}

with shared secret 'patrick':

69a36c60efdbd6bab822c09553c9602e282b125cf165c6dd64800b00477b16a9

Now we can complete the link by appending the signature to it:

https://pub1.pskt.io/c/{programId or campaignId}?data=eyJwZXJzb24uc3VybmFtZSI6Iktvc3Rlcm1hbiIsInBlcnNvbi5mb3JlbmFtZSI6IlBhdHJpY2siLCJwZXJzb24uZW1haWwiOiJwYXRyaWNrQHBhc3NraXQuY29tIiwicGVyc29uLmRpc3BsYXlOYW1lIjoiUGF0cmljayBLb3N0ZXJtYW4iLCJtZW1iZXJzLm1lbWJlci5wcm9maWxlSW1hZ2UiOiJodHRwczogLy9wYXNza2l0LmNvbS9wYXRyaWNrLnBuZyJ9
&sig=69a36c60efdbd6bab822c09553c9602e282b125cf165c6dd64800b00477b16a9

Encrypted Links

In addition to the hashed link functionality, we have also added the functionality for generating encrypted links.

We recommend this over hashed SmartPass links, since ultimately it is more secure than the signature hash since the whole payload is encrypted. The process for this is similar but instead of generating a signature hash for the link, you encrypt the data payload with AES CBC encryption + random IV. 

The encrypted link has the format:

https://pub1.pskt.io/c/{programId or campaignId}?data={encryptedData}&iv={randomIV}

If you have a CSV of your data, you can use our link generator tool, which simplify creates and encrypts the links for you (no code knowledge needed!):

Did this answer your question?