How to use the PassKit TypeScript SDK

The QuickStart includes examples for:

This guide will help you configure your credentials, run the TypeScript QuickStart and test the included examples.

Before using the TypeScript QuickStart, you will need:

The QuickStart supports both ESM and CommonJS builds.

The TypeScript QuickStart is available from the PassKit TypeScript gRPC QuickStart repository.

Clone the repository:

Install the project and its dependencies:

The QuickStart installs the PassKit TypeScript gRPC SDK and builds it during installation.

Alternatively, you can download the repository as a ZIP from GitHub, extract it, open a terminal in the extracted folder and run npm install.

The PassKit SDK uses SDK credentials to securely authenticate with the PassKit API.

To generate and download your SDK 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 TypeScript, you will need:

Create a folder named certs in the root of the QuickStart repository.

Add all three SDK credential files to this folder:

The credential files are ignored by Git and should not be committed to source control.

Create your local .env file by copying .env.example:

Open .env and set:

Replace your_passphrase with the password you created when generating your SDK credentials.

The default credential configuration is:

You do not need to manually decrypt key.pem. The QuickStart uses PASSKIT_PASSPHRASE to load your encrypted SDK private key.

Your SDK credentials and .env file are ignored by Git. Never commit or share them.

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:

For United States accounts, use:

The default gRPC port is:

Your PassKit account data exists in one region, so make sure the configured address matches the API region shown in your account.

Once your dependencies, credentials and .env file have been configured, you can run one of the four guided workflows.

To run all four workflows, use:

Each workflow creates the resources required for the example and demonstrates common PassKit API operations.

When successful, the workflow outputs the generated pass URL.

When a workflow successfully issues a pass, the QuickStart outputs a PassKit pass URL.

Open the URL on a compatible mobile device to add the pass to Apple Wallet or Google Wallet.

If you open the URL on a desktop, you can use the displayed QR code to open the pass on your phone.

Each workflow demonstrates common operations available through the PassKit TypeScript SDK.

The loyalty workflow demonstrates:

The coupons workflow demonstrates:

The event tickets workflow demonstrates:

The flights workflow demonstrates:

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:

Replace the example value with the Pass Type Identifier for your own Apple Wallet certificate.

By default, each workflow cleans up the test resources it creates.

If you want to retain the resources so you can inspect them in your PassKit account, set:

Alternatively, pass the --keep option when running a workflow.

For example:

When resources are retained, you will need to remove them manually from your PassKit account.

For normal QuickStart use, leave:

You can optionally provide a recipient email address in .env:

For example:

Leave this value empty if you do not want to provide a recipient email address.

The TypeScript QuickStart supports both ESM and CommonJS.

ESM is the default.

To run the TypeScript source using ESM:

To build and run using CommonJS:

You can build both formats with:

The compiled output is created in:

To run compiled ESM output:

To run compiled CommonJS output:

You can also build the formats individually:

This allows you to use the QuickStart as a reference whether your existing TypeScript or Node.js application uses ESM or CommonJS.

Once you have successfully run a QuickStart workflow, use its implementation as a reference when building your own TypeScript application.

The focused examples are contained in the quickstarts directory and demonstrate the recommended structure for working with:

The shared PassKit client also provides access to additional services including:

This allows your application to access the wider TypeScript SDK without creating a separate connection for each service.

The QuickStart uses ConnectRPC with a reusable HTTP/2 transport, allowing requests to share the underlying gRPC connection.

The main configuration options available in .env are:

PASSKIT_PASSPHRASE
The password used to decrypt your SDK private key. This is required.

PASSKIT_ADDRESS
The PassKit API region. The default is grpc.pub1.passkit.io.

PASSKIT_PORT
The gRPC port. The default is 443.

PASSKIT_ROOT_CERT
The path to ca-chain.pem.

PASSKIT_PRIVATE_KEY
The path to your encrypted key.pem.

PASSKIT_CERTIFICATE
The path to certificate.pem.

PASSKIT_RECIPIENT_EMAIL
An optional email address to use when issuing passes.

PASSKIT_APPLE_CERTIFICATE
The Apple Wallet Pass Type Identifier required by the flights example.

PASSKIT_KEEP_ASSETS
Controls whether generated resources are retained after running a workflow. The default is false.

The legacy PASSKIT_GRPC_ADDRESS and PASSKIT_GRPC_PORT configuration names are also supported.

The repository includes checks that can be run without connecting to PassKit.

Run:

This:

You can also run:

These checks are useful after modifying the QuickStart or when using it as the basis for your own application.

Check your installed Node.js version:

The TypeScript QuickStart requires Node.js 20 or later.

Confirm that the certs folder contains:

Also make sure you are running commands from the root of the QuickStart repository.

Check the value of:

This must be the password you created when generating your SDK credentials, not your PassKit account password.

You do not need to manually decrypt key.pem.

Check Developer Tools → API Region in your PassKit account and confirm that PASSKIT_ADDRESS matches your region.

For Europe:

For the United States:

Also make sure certificate.pem, key.pem and ca-chain.pem belong to the same set of SDK credentials.

Confirm that an Apple Wallet certificate has been uploaded to PassKit and that its Pass Type Identifier has been added to:

Cleanup is best-effort. If a workflow is interrupted or cleanup fails, some generated resources may remain.

Remove any remaining test resources manually from your PassKit account.

Also check:

If this is set to true, the QuickStart intentionally retains generated resources.

Once you have successfully run the TypeScript QuickStart, you can use the workflows and shared client as a reference when implementing PassKit in your own TypeScript application.

For additional methods, request fields and response definitions, refer to the PassKit developer documentation.