The QuickStart includes examples for:
Membership and loyalty cards
Coupons
Event tickets
Boarding passes
This guide will help you configure your credentials, run the Ruby QuickStart and test the included examples.
Before You Start
Before using the Ruby QuickStart, you will need:
A PassKit account.
Your PassKit SDK credentials.
Ruby 3.2 or later.
Bundler.
An Apple Wallet certificate if you want to run the flights example.
Download the QuickStart
The Ruby QuickStart is available from the PassKit Ruby gRPC QuickStart repository.
Clone the repository:
git clone https://github.com/PassKit/passkit-ruby-grpc-quickstart.git
cd passkit-ruby-grpc-quickstart
Alternatively, download the repository as a ZIP from GitHub, extract it and open a terminal in the extracted folder.
Install the required dependencies:
bundle install
The QuickStart uses the official PassKit Ruby gRPC SDK.
Get Your PassKit SDK Credentials
The PassKit SDK uses SDK credentials to securely authenticate with the PassKit API.
To generate and download your SDK credentials:
Log in to your PassKit account.
Click your account icon in the bottom-left corner, then select Account from the menu.
Select Developer Tools.
Under Account Credentials, locate SDK Credentials.
Follow the on-screen instructions to generate and download your credentials.
When generating your SDK credentials, you will be asked to create a password. This password encrypts your private key and is separate from your PassKit account password.
For Ruby, you will need:
certificate.pemkey.pemca-chain.pem
Important: Keep your SDK credentials and credential password private. Do not commit or share them through Git or another source control repository.
Add Your SDK Credentials
Add your three SDK credential files to the certs folder in the QuickStart repository.
Your project should contain:
passkit-ruby-grpc-quickstart/
├── certs/
│ ├── ca-chain.pem
│ ├── certificate.pem
│ └── key.pem
The credential files are excluded from Git and should not be committed to source control.
Configure the QuickStart
Create your local .env file by copying .env.example:
cp .env.example .env
The default credential paths are:
PASSKIT_CERTIFICATE=certs/certificate.pem
PASSKIT_KEY=certs/key.pem
PASSKIT_CA_CHAIN=certs/ca-chain.pem
If your private key is encrypted, add the password you created when generating your SDK credentials:
PASSKIT_KEY_PASSWORD=your-sdk-credential-password
The QuickStart decrypts and converts the private key in memory when required for compatibility with Ruby gRPC. Your original key.pem file is not modified.
This means you do not need to manually decrypt your private key.
Your .env file and SDK credentials should remain private and should not be committed to source control.
Configure Your API Region
Your QuickStart must connect to the API region associated with your PassKit account.
You can find your API region under Developer Tools → API Region in your PassKit account.
For European accounts, use:
PASSKIT_GRPC_HOST=grpc.pub1.passkit.io
For United States accounts, use:
PASSKIT_GRPC_HOST=grpc.pub2.passkit.io
The default gRPC port is:
PASSKIT_GRPC_PORT=443
Make sure the configured API region matches the region shown in your PassKit account.
Run the QuickStart
Once your credentials and .env file have been configured, you can run one of the four guided workflows.
Membership and Loyalty
bundle exec ruby bin/quickstart membership
Coupons
bundle exec ruby bin/quickstart coupons
Event Tickets
bundle exec ruby bin/quickstart event-tickets
Flights and Boarding Passes
bundle exec ruby bin/quickstart flights
Each workflow validates the required configuration, connects to PassKit and performs a series of common operations for the selected PassKit product.
The resources created by the workflow are automatically cleaned up after the example completes.
What the Examples Demonstrate
Each workflow demonstrates common operations available through the PassKit Ruby SDK.
Membership and Loyalty
The membership workflow demonstrates operations including:
Creating images and a template
Creating a program and tier
Enrolling a member
Checking a member in and out
Earning points
Burning points
Updating a member
Retrieving members
Listing and counting members
Retrieving member event history
Cleaning up generated resources
Coupons
The coupons workflow demonstrates operations including:
Creating images and a template
Creating a campaign and offer
Issuing a coupon
Updating a coupon
Retrieving coupons
Listing and counting coupons
Redeeming a coupon
Voiding a coupon
Cleaning up generated resources
Event Tickets
The event tickets workflow demonstrates operations including:
Creating images and a template
Creating a production
Creating a venue and event
Creating a ticket type
Issuing an event ticket
Updating a ticket
Looking up tickets by ID, ticket number and order number
Listing tickets
Validating a ticket
Redeeming a ticket
Cleaning up generated resources
Flights
The flights workflow demonstrates operations including:
Creating images and a boarding pass template
Creating or reusing a carrier
Creating or reusing airports
Creating a flight
Creating a flight designator
Retrieving flight and designator information
Issuing a boarding pass
Retrieving a boarding pass
Cleaning up generated resources
Existing carriers and airports that are reused by the example are not deleted during cleanup.
Running the Flights Example
The flights workflow requires an Apple Wallet certificate to be uploaded to your PassKit account.
Add the Pass Type Identifier for your Apple Wallet certificate to .env:
PASSKIT_APPLE_CERTIFICATE=pass.com.example.airline
Replace the example value with the Pass Type Identifier for your own Apple Wallet certificate.
Sending a Welcome Email
Some examples can use an email address when issuing passes.
Add your email address to .env:
PASSKIT_EMAIL=your-email@example.com
Use an email address you have access to when testing the QuickStart.
Exploring the SDK
The guided workflows demonstrate common PassKit operations, but the Ruby SDK provides additional functionality.
To view the methods currently available through the SDK, run:
bundle exec ruby bin/quickstart operations
The operations command is read-only and does not modify your PassKit account.
It lists the SDK method surface available through services including:
Membership
Coupons
Event tickets
Flights
Images
Templates
Distribution
Messages
Analytics
Raw passes
Scheduling
Certificates
Users
Integrations
This can be useful when looking for functionality that is not demonstrated by one of the four guided workflows.
Using the Ruby SDK in Your Application
Once you have successfully run a QuickStart workflow, you can use its implementation as a reference when building your own Ruby application.
The QuickStart provides a shared PassKit client and reusable connection pool.
For example:
require "passkit"
config = PassKit::Config.load
config.validate!
pool = PassKit::ConnectionPool.new(config)
pool.with do |client|
request = Io::Id.new(id: "your-program-id")
program = client.call(:membership, :get_program, request)
puts program.name
end
Generated SDK RPC names use Ruby snake case, such as:
create_program
list_coupons_by_coupon_campaign
issue_ticket
create_boarding_pass
Streaming responses can also be enumerated using standard Ruby patterns.
Use the guided workflows as a reference for creating the required PassKit resources in the correct order.
Test Your Setup
The repository includes tests that do not connect to PassKit or modify your account.
Run the tests with:
bundle exec rake test
You can also run RuboCop:
bundle exec rubocop
These commands are useful when modifying the QuickStart or using its code as the basis for your own integration.
Troubleshooting
Ruby is not recognised
Check that Ruby 3.2 or later is installed:
ruby --version
If Ruby is unavailable or the installed version is older than 3.2, install a supported version before continuing.
Bundler is not recognised
Check that Bundler is installed:
bundle --version
If necessary, install it with:
gem install bundler
Then run:
bundle install
from the QuickStart repository.
Credential files cannot be found
Confirm that your certs folder contains:
certificate.pem key.pem ca-chain.pem
Also check that the credential paths in .env match the location of these files.
Private key cannot be decrypted
If your key.pem is encrypted, make sure:
PASSKIT_KEY_PASSWORD
contains the password you created when generating your SDK credentials.
This is separate from your PassKit account password.
You do not need to manually decrypt or modify key.pem. The QuickStart handles the required conversion in memory.
Authentication or connection fails
Check Developer Tools → API Region in your PassKit account and confirm that PASSKIT_GRPC_HOST matches your region.
Use:
grpc.pub1.passkit.io
for Europe or:
grpc.pub2.passkit.io
for the United States.
Also make sure certificate.pem, key.pem and ca-chain.pem belong to the same set of SDK credentials.
Flights do not run
Confirm that an Apple Wallet certificate has been uploaded to PassKit and that its Pass Type Identifier has been added to:
PASSKIT_APPLE_CERTIFICATE
Next Steps
Once you have successfully run the Ruby QuickStart, you can use the workflows and shared API as a reference when implementing PassKit in your own Ruby application.
For additional methods, request fields and response definitions, refer to the PassKit developer documentation.