PassNinja

https://www.passninja.com/documentation
Admin
PassNinja is a platform and API for creating, managing, and distributing NFC-enabled digital wallet...
Tokens:23,877
Snippets:195
Trust Score:7.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install PassNinja SDKs

Source: https://www.passninja.com/documentation/sdks

Commands to install PassNinja libraries using standard package managers.

```bash
pip install passninja
```

```bash
gem install passninja
```

```bash
npm install @passninja/passninja-js
```

--------------------------------

### Install PassNinja CLI on Windows

Source: https://www.passninja.com/documentation/sdks

Use PowerShell to download and install the PassNinja CLI binary on Windows.

```powershell
irm https://github.com/flomio/passninja-cli/releases/latest/download/install.ps1 | iex
passninja auth
```

```powershell
irm https://github.com/flomio/passninja-cli/releases/latest/download/install.ps1 | iex
# Verify the install
passninja version
```

--------------------------------

### GET /v1/applications

Source: https://www.passninja.com/documentation/api-reference

List every application on your account.

```APIDOC
## GET /v1/applications

### Description
List every application on your account.

### Method
GET

### Endpoint
https://api.passninja.com/v1/applications

### Response
#### Success Response (200)
- **applications** (array) - List of application objects
```

--------------------------------

### List Pass Templates Response Examples

Source: https://www.passninja.com/documentation/api-reference

Examples of the JSON response structure for Apple and Google pass templates.

```json
{
  "id": "ptk_0x216",
  "platform": "apple",
  "apple": {
    "vas_merchant_id": "pass.com.passninja.loyalty",
    "vas_private_key_pem": "-----BEGIN EC PRIVATE KEY-----\n...\n-----END EC PRIVATE KEY-----\n"
  },
  "google": null
}
```

```json
{
  "id": "ptk_0x217",
  "platform": "google",
  "apple": null,
  "google": {
    "smart_tap_collector_id": "77501435",
    "smart_tap_key_version": "1",
    "smart_tap_private_key_pem": "-----BEGIN EC PRIVATE KEY-----\n...\n-----END EC PRIVATE KEY-----\n"
  }
}
```

--------------------------------

### Install PassNinja CLI on macOS or Linux

Source: https://www.passninja.com/documentation/sdks

Use Homebrew to install the PassNinja CLI binary on macOS or Linux systems.

```bash
brew tap flomio/passninja
brew install passninja
passninja auth
```

```bash
brew tap flomio/passninja
brew install passninja
# Verify the install
passninja version
```

--------------------------------

### Pass retrieval response example

Source: https://www.passninja.com/documentation/api-reference

Example JSON response containing pass metadata and field values.

```json
{
  "id": "<SERIAL_NUMBER>",
  "passTemplate": "<YOUR_TEMPLATE_ID>",
  "serialNumber": "<SERIAL_NUMBER>",
  "urls": {
    "landing": "https://i.installpass.es/p/<SERIAL_NUMBER>"
  },
  "pass": {
    "member.level": "gold",
    "discount": "100%",
    "member.name": "John"
  }
}
```

--------------------------------

### Decryption response example

Source: https://www.passninja.com/documentation/api-reference

Example JSON response returned after a successful decryption request.

```json
{
  "encrypted": "55166a97002...1ea070f0d4fe88887",
  "decrypted": "fee4a257185906b92a",
  "timeOfScan": "2026-07-24T18:00:00Z"
}
```

--------------------------------

### Example pass creation response

Source: https://www.passninja.com/documentation/api-reference

The JSON object returned upon successful pass creation.

```json
{
  "id": "<SERIAL_NUMBER>",
  "passTemplate": "<YOUR_TEMPLATE_ID>",
  "serialNumber": "<SERIAL_NUMBER>",
  "urls": {
    "landing": "https://i.installpass.es/p/<SERIAL_NUMBER>"
  }
}
```

--------------------------------

### Webhook Event Payload Example

Source: https://www.passninja.com/documentation/api-reference

Example of a CloudEvents 1.0 structured-mode JSON payload delivered via HTTP POST.

```json
{
  "specversion": "1.0",
  "id": "38656a51-a892-8717-587b-f59de5163c2a",
  "source": "https://api.passninja.com/accounts/aid_0xa01",
  "type": "pn.pass.installed",
  "datacontenttype": "application/json",
  "time": "2026-05-12T18:25:43.511Z",
  "pnattempt": 1,
  "data": {
    "passTemplate": "ptk_0x216",
    "passId": "fee4a257185906b92a",
    "metadata": {
      "member.name": "John",
      "discount": "50%"
    }
  }
}
```

--------------------------------

### Example list passes response

Source: https://www.passninja.com/documentation/api-reference

The JSON object returned when listing passes, including pagination metadata.

```json
{
  "passes": [
    {
      "id": "<SERIAL_NUMBER>",
      "passTemplate": "<YOUR_TEMPLATE_ID>",
      "serialNumber": "<SERIAL_NUMBER>",
      "urls": {
        "landing": "https://i.installpass.es/p/<SERIAL_NUMBER>"
      },
      "issuedDate": "2024-04-23T10:15:00Z",
      "installedDate": "2024-04-23T14:30:00Z",
      "status": "Active",
      "recipient": {
        "sms": "+15551234567",
        "email": "user@example.com"
      }
    }
  ],
  "meta": {
    "currentPage": 1,
    "totalPages": 5,
    "totalCount": 42,
    "perPage": 10
  }
}
```

--------------------------------

### GET /v1/webhooks

Source: https://www.passninja.com/documentation/api-reference

Retrieves a list of webhook subscriptions for the calling account.

```APIDOC
## GET /v1/webhooks

### Description
Returns subscriptions in the calling account, newest first.

### Method
GET

### Endpoint
/v1/webhooks

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number (default 1).
- **perPage** (integer) - Optional - Items per page (default 50, max 100).
- **passTemplate** (string) - Optional - Filter by pass template ID.
```

--------------------------------

### Get a Pass Template

Source: https://www.passninja.com/documentation/api-reference

Retrieves details for a specific template by its ID.

```bash
curl -X GET 'https://api.passninja.com/v1/pass_templates/<YOUR_TEMPLATE_ID>' \
  -H 'X-API-KEY: <YOUR_API_KEY>' \
  -H 'X-ACCOUNT-ID: <YOUR_ACCOUNT_ID>'
```

```json
{
  "id": "<YOUR_TEMPLATE_ID>",
  "name": "Loyalty Card",
  "platform": "apple",
  "style": "loyalty",
  "issuedPassCount": 150,
  "installedPassCount": 89
}
```

--------------------------------

### GET /v1/webhooks/<ID>

Source: https://www.passninja.com/documentation/api-reference

Retrieves details for a specific webhook subscription.

```APIDOC
## GET /v1/webhooks/<ID>

### Description
Returns the details of a specific webhook subscription. The bearer token is never included.

### Method
GET

### Endpoint
/v1/webhooks/<ID>

### Parameters
#### Path Parameters
- **ID** (string) - Required - The unique identifier of the webhook subscription.
```

--------------------------------

### Get Pass Template Fields

Source: https://www.passninja.com/documentation/api-reference

Fetches the field schema for a template, including visibility and requirement flags.

```bash
curl -X GET 'https://api.passninja.com/v1/pass_templates/fields/<YOUR_TEMPLATE_ID>' \
  -H 'X-API-KEY: <YOUR_API_KEY>' \
  -H 'X-ACCOUNT-ID: <YOUR_ACCOUNT_ID>'
```

```json
{
  "id": "<YOUR_TEMPLATE_ID>",
  "platform": "apple",
  "fields": [
    { "api_field_name": "account.name", "visible": true, "required": true },
    { "api_field_name": "nfc.message", "visible": true, "required": false },
    { "api_field_name": "barcode.data", "visible": false, "required": false }
  ]
}
```

--------------------------------

### Legacy webhook subscription format

Source: https://www.passninja.com/documentation/api-reference

Example of the deprecated webhook payload format used by subscriptions created before the CloudEvents rollout.

```json
{
  "passTemplate": "ptk_0x216",
  "passId": "fee4a257185906b92a",
  "event": "install",
  "eventDate": "2026-05-12T18:25:43.511Z",
  "attempt": 1
}
```

--------------------------------

### Get a webhook subscription

Source: https://www.passninja.com/documentation/api-reference

Retrieves details for a specific subscription by ID. The bearer token is omitted from this response.

```bash
curl -X GET 'https://api.passninja.com/v1/webhooks/47' \
  -H 'X-API-KEY: <YOUR_API_KEY>' \
  -H 'X-ACCOUNT-ID: <YOUR_ACCOUNT_ID>'
```

--------------------------------

### Get a Pass

Source: https://www.passninja.com/documentation/sdks

Retrieve a specific pass by its pass template and serial number.

```APIDOC
## Get a Pass

### Description
Retrieve a specific pass by its pass template and serial number.

### Method
SDK Method: `passes.get(template_id, serial_number)`

### Parameters
- **template_id** (string) - Required - The unique identifier for the pass template.
- **serial_number** (string) - Required - The unique serial number of the pass.
```

--------------------------------

### GET /v1/readers/<id>/config

Source: https://www.passninja.com/documentation/api-reference

Returns the reader-agnostic identity values and EC decryption keys for NFC readers.

```APIDOC
## GET /v1/readers/<id>/config

### Description
Returns the reader-agnostic identity values and EC decryption keys a physical NFC reader needs to read this template's Apple (VAS) and/or Google (Smart Tap) passes.

### Method
GET

### Endpoint
https://api.passninja.com/v1/readers/<id>/config

### Parameters
#### Path Parameters
- **id** (string) - Required - The pass template identifier
```

--------------------------------

### Get merged reader configuration

Source: https://www.passninja.com/documentation/api-reference

Retrieves merged reader-config values across all bound templates. Requires API key and account ID headers.

```bash
curl -X GET 'https://api.passninja.com/v1/readers/<READER_ID>/config' \
   -H 'X-API-KEY: <YOUR_API_KEY>' \
   -H 'X-ACCOUNT-ID: <YOUR_ACCOUNT_ID>'
```

```json
{
  "id": "1",
  "templates": [
    { "id": "ptk_0x216", "platform": "apple", "apple": { "vas_merchant_id": "pass.com.example", "vas_private_key_pem": "-----BEGIN EC PRIVATE KEY-----..." }, "google": null }
  ]
}
```

--------------------------------

### GET /v1/readers/<READER_ID>/config

Source: https://www.passninja.com/documentation/api-reference

Returns the reader-config values (Apple merchant id / Google collector id + key version and their decryption keys) merged across all of the reader's bound templates.

```APIDOC
## GET /v1/readers/<READER_ID>/config

### Description
Return the reader-config values (Apple merchant id / Google collector id + key version and their decryption keys) merged across all of the reader's bound templates.

### Method
GET

### Endpoint
https://api.passninja.com/v1/readers/<READER_ID>/config

### Parameters
#### Path Parameters
- **READER_ID** (string) - Required - The unique identifier of the reader.

### Response
#### Success Response (200)
- **id** (string) - Reader ID
- **templates** (array) - List of bound templates

#### Response Example
{
  "id": "1",
  "templates": [
    { "id": "ptk_0x216", "platform": "apple", "apple": { "vas_merchant_id": "pass.com.example", "vas_private_key_pem": "-----BEGIN EC PRIVATE KEY-----..." }, "google": null }
  ]
}
```

--------------------------------

### PATCH /v1/pass_templates/<YOUR_TEMPLATE_ID>

Source: https://www.passninja.com/documentation/api-reference

Updates an existing template's name, field settings, install constraints, sharing configuration, and auto top-up settings. Requires the enterprise-api-service entitlement.

```APIDOC
## PATCH /v1/pass_templates/<YOUR_TEMPLATE_ID>

### Description
Update an existing template's name, its scalar field settings, and its install-constraint, disable-sharing, and auto top-up configuration. Changes made through the API publish immediately.

### Method
PATCH

### Endpoint
https://api.passninja.com/v1/pass_templates/<YOUR_TEMPLATE_ID>

### Parameters
#### Path Parameters
- **id** (string) - Required - The pass template identifier.

#### Request Body
- **name** (string) - Optional - New human label for the template, ≤ 120 characters.
- **fields** (object) - Optional - An object keyed by api field name; each value may set default_value, visible, required, and api_field_name.
- **install_constraints** (object) - Optional - Limit where each issued pass can install (device, browser, ip).
- **disable_sharing** (object) - Optional - Stop passes from being shared between devices/holders (apple, google).
- **top_up** (object) - Optional - Auto-refill the prepaid balance (auto_recharge, balance_trigger, top_up_target).
- **reader** (string) - Optional - Pair this template with a reader from the template side.

### Request Example
{
  "fields": {
    "primary.value": { "api_field_name": "guest.name" },
    "background.color": { "default_value": "rgb(0, 0, 255)" }
  }
}

### Response
#### Success Response (200)
- **id** (string) - The template identifier.
- **name** (string) - The template name.
- **fields** (array) - The resulting api-mapped fields.

#### Response Example
{
  "id": "ptk_0x216",
  "name": "Loyalty Card",
  "fields": [
    { "api_field_name": "guest.name", "default_value": "", "visible": true, "required": false },
    { "api_field_name": "background.color", "default_value": "rgb(0, 0, 255)", "visible": true, "required": false }
  ]
}
```

--------------------------------

### Get Reader Configuration

Source: https://www.passninja.com/documentation/api-reference

Retrieves decryption keys and identity values for NFC readers. Requires a valid reader ID.

```bash
curl -X GET 'https://api.passninja.com/v1/readers/<READER_ID>/config' \
  -H 'X-API-KEY: <YOUR_API_KEY>' \
  -H 'X-ACCOUNT-ID: <YOUR_ACCOUNT_ID>'
```

--------------------------------

### List applications

Source: https://www.passninja.com/documentation/api-reference

Retrieve all applications associated with the account.

```bash
curl -X GET 'https://api.passninja.com/v1/applications' \
  -H 'X-API-KEY: <YOUR_API_KEY>' \
  -H 'X-ACCOUNT-ID: <YOUR_ACCOUNT_ID>'
```

```json
{
  "applications": [
    { "id": "app_0x1", "name": "Front gate validation", "kind": "validate", "passTemplate": "ptk_0x216", "active": true, "readerCount": 2 }
  ]
}
```

--------------------------------

### Create an application

Source: https://www.passninja.com/documentation/api-reference

Registers a new application bound to a specific pass template. Requires appropriate entitlements based on the chosen kind.

```bash
curl -X POST 'https://api.passninja.com/v1/applications' \
  -H 'X-API-KEY: <YOUR_API_KEY>' \
  -H 'X-ACCOUNT-ID: <YOUR_ACCOUNT_ID>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Front gate validation",
    "kind": "validate",
    "passTemplate": "<YOUR_TEMPLATE_ID>",
    "config": { "rescanWindowSeconds": 14400 }
  }'
```

--------------------------------

### Client Initialization

Source: https://www.passninja.com/documentation/sdks

Initialize the PassNinja client using your account credentials.

```APIDOC
## Client Initialization

### Description
Initialize the PassNinja client with your API credentials (API Key and Account ID) to begin making requests.

### Supported Languages
- Python
- Ruby
- Node.js
- Swift
- Java
- C#
- PHP

### Initialization Examples

#### Python
```python
import passninja
pass_ninja_client = passninja.PassNinjaClient(account_id, api_key)
```

#### Ruby
```ruby
require 'passninja'
pass_ninja_client = PassNinja::Client.new(account_id, api_key)
```

#### Node.js
```javascript
const PassNinja = require('@passninja/passninja-js');
const passNinjaClient = new PassNinja.Client(accountId, apiKey);
```

#### Swift
```swift
import PassNinja
let passNinjaClient = PassNinjaClient(accountId: accountId, apiKey: apiKey)
```

#### Java
```java
import com.passninja.PassNinja;
PassNinja passNinjaClient = new PassNinja(accountId, apiKey);
```

#### C#
```csharp
using PassNinja;
var passNinjaClient = new PassNinjaClient(accountId, apiKey);
```

#### PHP
```php
require 'vendor/autoload.php';
$passNinjaClient = new PassNinja\Client($accountId, $apiKey);
```
```

--------------------------------

### GET /v1/readers

Source: https://www.passninja.com/documentation/api-reference

List all registered readers.

```APIDOC
## GET /v1/readers

### Description
List your readers.

### Method
GET

### Endpoint
https://api.passninja.com/v1/readers
```

--------------------------------

### List Pass Templates via CLI

Source: https://www.passninja.com/documentation/sdks

Use the CLI to list templates, optionally outputting as JSON for integration with tools like jq.

```bash
passninja pass-template list # JSON for piping into jq / your tooling passninja pass-template list --output json
```

--------------------------------

### Initialize PassNinja Client

Source: https://www.passninja.com/documentation/sdks

Initialize the PassNinja client using your Account ID and API Key for various programming languages.

```python
import passninja
account_id = '<YOUR_ACCOUNT_ID>'
api_key = '<YOUR_API_KEY>'
pass_ninja_client = passninja.PassNinjaClient(
    account_id, api_key
)
```

```ruby
require 'passninja'
account_id = '<YOUR_ACCOUNT_ID>'
api_key = '<YOUR_API_KEY>'
pass_ninja_client = PassNinja::Client.new(account_id, api_key)
```

```javascript
const PassNinja = require('@passninja/passninja-js');
const accountId = '<YOUR_ACCOUNT_ID>';
const apiKey = '<YOUR_API_KEY>';
const passNinjaClient = new PassNinja.Client(accountId, apiKey);
```

```swift
import PassNinja
let accountId = "<YOUR_ACCOUNT_ID>"
let apiKey = "<YOUR_API_KEY>"
let passNinjaClient = PassNinjaClient(accountId: accountId, apiKey: apiKey)
```

```java
import com.passninja.PassNinja;
String accountId = "<YOUR_ACCOUNT_ID>";
String apiKey = "<YOUR_API_KEY>";
PassNinja passNinjaClient = new PassNinja(accountId, apiKey);
```

```csharp
using PassNinja;
var accountId = "<YOUR_ACCOUNT_ID>";
var apiKey = "<YOUR_API_KEY>";
var passNinjaClient = new PassNinjaClient(accountId, apiKey);
```

```php
require 'vendor/autoload.php';
$accountId = '<YOUR_ACCOUNT_ID>';
$apiKey = '<YOUR_API_KEY>';
$passNinjaClient = new PassNinja\Client($accountId, $apiKey);
```

--------------------------------

### Create a webhook subscription

Source: https://www.passninja.com/documentation/api-reference

Creates a new subscription and returns a bearer token. The token is only provided in the initial response and must be persisted immediately.

```bash
curl -X POST 'https://api.passninja.com/v1/webhooks' \
  -H 'X-API-KEY: <YOUR_API_KEY>' \
  -H 'X-ACCOUNT-ID: <YOUR_ACCOUNT_ID>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Production install handler",
    "url": "https://example.com/passninja/webhook",
    "subscribedEvents": ["pn.pass.installed", "pn.pass.uninstalled"]
  }'
```

```json
{
  "id": "47",
  "name": "Production install handler",
  "url": "https://example.com/passninja/webhook",
  "authMethod": "bearer_token",
  "subscribedEvents": ["pn.pass.installed", "pn.pass.uninstalled"],
  "passTemplate": null,
  "active": true,
  "createdAt": "2026-05-12T18:00:00.000Z",
  "updatedAt": "2026-05-12T18:00:00.000Z",
  "bearerToken": "wbk_b3d6…"
}
```

--------------------------------

### GET /v1/pass_templates/<id>

Source: https://www.passninja.com/documentation/api-reference

Retrieves details about a specific pass template using its template ID.

```APIDOC
## GET /v1/pass_templates/<id>

### Description
Retrieves details about a specific pass template using its template ID.

### Method
GET

### Endpoint
https://api.passninja.com/v1/pass_templates/<id>

### Parameters
#### Path Parameters
- **id** (string) - Required - The pass template identifier

### Response
#### Success Response (200)
- **id** (string) - The pass template identifier
- **name** (string) - Template name
- **platform** (string) - Platform (apple or google)
- **style** (string) - Pass style
- **issuedPassCount** (integer) - Total passes issued
- **installedPassCount** (integer) - Total passes installed

#### Response Example
{
  "id": "<YOUR_TEMPLATE_ID>",
  "name": "Loyalty Card",
  "platform": "apple",
  "style": "loyalty",
  "issuedPassCount": 150,
  "installedPassCount": 89
}
```

--------------------------------

### Application creation response

Source: https://www.passninja.com/documentation/api-reference

The JSON response returned upon successfully creating an application.

```json
{
  "id": "app_0x1",
  "name": "Front gate validation",
  "description": null,
  "kind": "validate",
  "passTemplate": "ptk_0x216",
  "config": { "rescanWindowSeconds": 14400 },
  "active": true,
  "createdAt": "2026-07-24T18:00:00Z",
  "updatedAt": "2026-07-24T18:00:00Z"
}
```

--------------------------------

### Create a Pass Template

Source: https://www.passninja.com/documentation/api-reference

Provision a new pass template using a POST request. Requires the enterprise-api-service entitlement.

```bash
curl -X POST 'https://api.passninja.com/v1/pass_templates' \
  -H 'X-API-KEY: <YOUR_API_KEY>' \
  -H 'X-ACCOUNT-ID: <YOUR_ACCOUNT_ID>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Loyalty Card",
    "platform": "apple",
    "style": "loyalty",
    "install_constraints": { "device": true },
    "disable_sharing": { "apple": true }
  }'
```

--------------------------------

### List Pass Templates via SDKs

Source: https://www.passninja.com/documentation/sdks

Retrieve and iterate through pass templates using the official SDKs for various languages.

```python
pass_templates = pass_ninja_client.pass_templates.find() for template in pass_templates: print(f"{template.id}: {template.name}") print(f" Issued: {template.issuedPassCount}") print(f" Installed: {template.installedPassCount}")
```

```ruby
pass_templates = pass_ninja_client.pass_templates.find pass_templates.each do |template| puts "#{template.id}: #{template.name}" puts " Issued: #{template.issuedPassCount}" puts " Installed: #{template.installedPassCount}" end
```

```javascript
const passTemplates = await passNinjaClient.passTemplates.find(); passTemplates.forEach(template => { console.log(`${template.id}: ${template.name}`); console.log(` Issued: ${template.issuedPassCount}`); console.log(` Installed: ${template.installedPassCount}`); });
```

```swift
let passTemplates = try await passNinjaClient.passTemplates.find() for template in passTemplates { print("\(template.id): \(template.name)") print(" Issued: \(template.issuedPassCount)") print(" Installed: \(template.installedPassCount)") }
```

```java
List<PassTemplate> passTemplates = passNinjaClient.passTemplates().find(); for (PassTemplate template : passTemplates) { System.out.println(template.getId() + ": " + template.getName()); System.out.println(" Issued: " + template.getIssuedPassCount()); System.out.println(" Installed: " + template.getInstalledPassCount()); }
```

```csharp
var passTemplates = await passNinjaClient.PassTemplates.Find(); foreach (var template in passTemplates) { Console.WriteLine($"{template.Id}: {template.Name}"); Console.WriteLine($" Issued: {template.IssuedPassCount}"); Console.WriteLine($" Installed: {template.InstalledPassCount}"); }
```

```php
$passTemplates = $passNinjaClient->passTemplates->find(); foreach ($passTemplates as $template) { echo $template->id . ": " . $template->name . "\n"; echo " Issued: " . $template->issuedPassCount . "\n"; echo " Installed: " . $template->installedPassCount . "\n"; }
```

--------------------------------

### POST /v1/applications

Source: https://www.passninja.com/documentation/api-reference

Creates a new application bound to a specific pass template for handling scan events.

```APIDOC
## POST /v1/applications

### Description
Creates an application bound to one pass template. The template binding is fixed once created.

### Method
POST

### Endpoint
/v1/applications

### Parameters
#### Request Body
- **name** (string) - Required - Human label, ≤ 120 characters.
- **kind** (string) - Required - One of 'log', 'validate', 'forward'.
- **passTemplate** (string) - Required - The template ID this application validates for.
- **config** (object) - Required - Per-kind settings including rescanWindowSeconds and endpointUrl.

### Response
#### Success Response (201)
- **id** (string) - The created application ID.
- **name** (string) - The application name.
- **kind** (string) - The application kind.
- **passTemplate** (string) - The bound template ID.
- **config** (object) - The configuration object.
- **active** (boolean) - Status of the application.
- **createdAt** (string) - Creation timestamp.
- **updatedAt** (string) - Last update timestamp.
```

--------------------------------

### Get a Specific Pass

Source: https://www.passninja.com/documentation/sdks

Retrieve details for a specific pass using its template ID and serial number.

```CLI
passninja pass get <YOUR_TEMPLATE_ID> <SERIAL_NUMBER> # Dump the raw API response (handy for debugging) passninja pass raw <YOUR_TEMPLATE_ID> <SERIAL_NUMBER>
```

```Python
detailed_pass_object = pass_ninja_client.passes.get( '<YOUR_TEMPLATE_ID>', '<SERIAL_NUMBER>' ) print(detailed_pass_object)
```

```Ruby
detailed_pass_object = pass_ninja_client.passes.get( '<YOUR_TEMPLATE_ID>', '<SERIAL_NUMBER>' ) puts detailed_pass_object
```

```Node.js
const detailedPassObject = await passNinjaClient.passes.get( '<YOUR_TEMPLATE_ID>', '<SERIAL_NUMBER>' ); console.log(detailedPassObject);
```

```Swift
let detailedPassObject = try await passNinjaClient.passes.get( "<YOUR_TEMPLATE_ID>", "<SERIAL_NUMBER>" ) print(detailedPassObject)
```

```Java
Pass detailedPassObject = passNinjaClient.passes().get( "<YOUR_TEMPLATE_ID>", "<SERIAL_NUMBER>" ); System.out.println(detailedPassObject);
```

```C#
var detailedPassObject = await passNinjaClient.Passes.Get( "<YOUR_TEMPLATE_ID>", "<SERIAL_NUMBER>" ); Console.WriteLine(detailedPassObject);
```

```PHP
$detailedPassObject = $passNinjaClient->passes->get( '<YOUR_TEMPLATE_ID>', '<SERIAL_NUMBER>' ); print_r($detailedPassObject);
```

--------------------------------

### Update an application

Source: https://www.passninja.com/documentation/api-reference

Modify application properties. Pass-template binding is immutable.

```bash
curl -X PATCH 'https://api.passninja.com/v1/applications/<APPLICATION_ID>' \
  -H 'X-API-KEY: <YOUR_API_KEY>' \
  -H 'X-ACCOUNT-ID: <YOUR_ACCOUNT_ID>' \
  -H 'Content-Type: application/json' \
  -d '{ "config": { "rescanWindowSeconds": 7200 } }'
```

--------------------------------

### Create a Pass via SDKs

Source: https://www.passninja.com/documentation/sdks

Create a pass by passing a template ID and a data object containing the pass fields.

```python
simple_pass_object = pass_ninja_client.passes.create( '<YOUR_TEMPLATE_ID>', { 'member.level': 'silver', 'discount': '50%', 'member.name': 'John' } ) print(simple_pass_object.serialNumber)
```

```ruby
simple_pass_object = pass_ninja_client.passes.create( '<YOUR_TEMPLATE_ID>', { 'member.level' => 'silver', 'discount' => '50%', 'member.name' => 'John' } ) puts simple_pass_object.serialNumber
```

```javascript
const simplePassObject = await passNinjaClient.passes.create( '<YOUR_TEMPLATE_ID>', { 'member.level': 'silver', 'discount': '50%', 'member.name': 'John' } ); console.log(simplePassObject.serialNumber);
```

```swift
let simplePassObject = try await passNinjaClient.passes.create( "<YOUR_TEMPLATE_ID>", [ "member.level": "silver", "discount": "50%", "member.name": "John" ] ) print(simplePassObject.serialNumber)
```

```java
Map<String, String> passData = new HashMap<>(); passData.put("member.level", "silver"); passData.put("discount", "50%"); passData.put("member.name", "John"); Pass simplePassObject = passNinjaClient.passes().create("<YOUR_TEMPLATE_ID>", passData); System.out.println(simplePassObject.getSerialNumber());
```

```csharp
var passData = new Dictionary<string, string> { { "member.level", "silver" }, { "discount", "50%" }, { "member.name", "John" } }; var simplePassObject = await passNinjaClient.Passes.Create("<YOUR_TEMPLATE_ID>", passData); Console.WriteLine(simplePassObject.SerialNumber);
```

```php
$simplePassObject = $passNinjaClient->passes->create( '<YOUR_TEMPLATE_ID>', [ 'member.level' => 'silver', 'discount' => '50%', 'member.name' => 'John' ] ); echo $simplePassObject->serialNumber . "\n";
```

--------------------------------

### GET /v1/pass_templates/fields/<id>

Source: https://www.passninja.com/documentation/api-reference

Retrieves the full field schema for a pass template, including visibility and requirement flags.

```APIDOC
## GET /v1/pass_templates/fields/<id>

### Description
Retrieves the full field schema for a pass template — every API mapped field with its visibility and requirement flags.

### Method
GET

### Endpoint
https://api.passninja.com/v1/pass_templates/fields/<id>

### Parameters
#### Path Parameters
- **id** (string) - Required - The pass template identifier

### Response
#### Success Response (200)
- **id** (string) - The pass template identifier
- **platform** (string) - Platform (apple or google)
- **fields** (array) - Array of field objects

#### Response Example
{
  "id": "<YOUR_TEMPLATE_ID>",
  "platform": "apple",
  "fields": [
    { "api_field_name": "account.name", "visible": true, "required": true },
    { "api_field_name": "nfc.message", "visible": true, "required": false },
    { "api_field_name": "barcode.data", "visible": false, "required": false }
  ]
}
```

--------------------------------

### Create a reader

Source: https://www.passninja.com/documentation/api-reference

Register a new NFC reader. The bearer token is returned only once.

```bash
curl -X POST 'https://api.passninja.com/v1/readers' \
  -H 'X-API-KEY: <YOUR_API_KEY>' \
  -H 'X-ACCOUNT-ID: <YOUR_ACCOUNT_ID>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Front gate",
    "location": "Torreón - Puerta 2",
    "applications": ["app_0x1"]
  }'
```

```json
{
  "id": "1",
  "name": "Front gate",
  "location": "Torreón - Puerta 2",
  "status": "active",
  "applications": [ { "id": "app_0x1", "name": "Front gate validation", "kind": "validate", "passTemplate": "ptk_0x216" } ],
  "serial": null,
  "token": "rdr_e159d817f592d22368728b93763780ffd2bf978b55654aa1"
}
```

--------------------------------

### GET /v1/webhooks/<ID>/results

Source: https://www.passninja.com/documentation/api-reference

Retrieves the delivery history for a specific webhook subscription, useful for diagnosing receiver-side issues.

```APIDOC
## GET /v1/webhooks/<ID>/results

### Description
Retrieves every delivery attempt for a webhook, including successful and failed attempts. Delivery history is retained for 15 days.

### Method
GET

### Endpoint
/v1/webhooks/<ID>/results

### Parameters
#### Path Parameters
- **ID** (string) - Required - The unique identifier of the webhook subscription.

### Response
#### Success Response (200)
- **webhookResults** (array) - List of delivery attempts.
- **page** (number) - Current page number.
- **perPage** (number) - Number of items per page.
- **total** (number) - Total count of results.
```

--------------------------------

### POST /v1/pass_templates

Source: https://www.passninja.com/documentation/api-reference

Programmatically provision a new pass template under your account. Requires the enterprise-api-service entitlement.

```APIDOC
## POST /v1/pass_templates

### Description
Programmatically provision a new pass template under your account. The template is seeded with its pass type's default fields.

### Method
POST

### Endpoint
https://api.passninja.com/v1/pass_templates

### Parameters
#### Request Body
- **name** (string) - Required - Human label for the template, ≤ 120 characters.
- **platform** (string) - Required - One of apple or google.
- **style** (string) - Required - Pass style identifier (e.g. access_control, coupon, ticket, loyalty).
- **install_constraints** (object) - Optional - Limit where each issued pass can install (device, browser, ip).
- **disable_sharing** (object) - Optional - Stop passes from being shared between devices/holders (apple, google).
- **top_up** (object) - Optional - Auto-refill the prepaid balance (auto_recharge, balance_trigger, top_up_target).
- **reader** (string) - Optional - Pair the new template with a reader at creation time.

### Request Example
{
  "name": "Loyalty Card",
  "platform": "apple",
  "style": "loyalty",
  "install_constraints": { "device": true },
  "disable_sharing": { "apple": true }
}

### Response
#### Success Response (201)
- **id** (string) - The unique identifier for the template.
- **name** (string) - The human label for the template.
- **platform** (string) - The target platform.
- **style** (string) - The pass style.
- **issuedPassCount** (integer) - Number of passes issued.
- **installedPassCount** (integer) - Number of passes installed.
- **createdAt** (string) - Creation timestamp.
- **updatedAt** (string) - Last update timestamp.

#### Response Example
{
  "id": "ptk_0x216",
  "name": "Loyalty Card",
  "platform": "apple",
  "style": "loyalty",
  "issuedPassCount": 0,
  "installedPassCount": 0,
  "createdAt": "2026-05-12T18:00:00Z",
  "updatedAt": "2026-05-12T18:00:00Z",
  "install_constraints": { "device": true, "browser": false, "ip": false },
  "disable_sharing": { "apple": true, "google": false },
  "top_up": { "auto_recharge": false, "balance_trigger": null, "top_up_target": null }
}
```

--------------------------------

### GET /v1/passes/<YOUR_TEMPLATE_ID>

Source: https://www.passninja.com/documentation/api-reference

Retrieves a list of passes for a specific pass template, supporting pagination and search by serial number.

```APIDOC
## GET /v1/passes/<YOUR_TEMPLATE_ID>

### Description
Retrieves a list of passes using its pass template identifier. Supports pagination and search.

### Method
GET

### Endpoint
https://api.passninja.com/v1/passes/<YOUR_TEMPLATE_ID>

### Parameters
#### Path Parameters
- **passTemplate** (string) - Required - The pass template identifier.

#### Query Parameters
- **page** (integer) - Optional - Page number for pagination.
- **perPage** (integer) - Optional - Number of passes per page.
- **search** (string) - Optional - Search passes by serial number.

### Response
#### Success Response (200)
- **passes** (array) - List of pass objects.
- **meta** (object) - Pagination metadata.

#### Response Example
{
  "passes": [
    {
      "id": "<SERIAL_NUMBER>",
      "passTemplate": "<YOUR_TEMPLATE_ID>",
      "serialNumber": "<SERIAL_NUMBER>",
      "urls": {
        "landing": "https://i.installpass.es/p/<SERIAL_NUMBER>"
      },
      "issuedDate": "2024-04-23T10:15:00Z",
      "installedDate": "2024-04-23T14:30:00Z",
      "status": "Active",
      "recipient": {
        "sms": "+15551234567",
        "email": "user@example.com"
      }
    }
  ],
  "meta": {
    "currentPage": 1,
    "totalPages": 5,
    "totalCount": 42,
    "perPage": 10
  }
}
```

--------------------------------

### List Pass Templates

Source: https://www.passninja.com/documentation/sdks

Retrieve a list of all pass templates for your account using the CLI or SDKs.

```APIDOC
## List Pass Templates

### Description
Retrieve a list of all pass templates for your account.

### SDK Methods
- **CLI**: `passninja pass-template list`
- **Python**: `pass_ninja_client.pass_templates.find()`
- **Ruby**: `pass_ninja_client.pass_templates.find`
- **Node.js**: `await passNinjaClient.passTemplates.find()`
- **Swift**: `try await passNinjaClient.passTemplates.find()`
- **Java**: `passNinjaClient.passTemplates().find()`
- **C#**: `await passNinjaClient.PassTemplates.Find()`
- **PHP**: `$passNinjaClient->passTemplates->find()`
```

--------------------------------

### List webhook subscriptions

Source: https://www.passninja.com/documentation/api-reference

Retrieves a paginated list of subscriptions for the calling account, ordered by newest first.

```bash
curl -X GET 'https://api.passninja.com/v1/webhooks?perPage=20' \
  -H 'X-API-KEY: <YOUR_API_KEY>' \
  -H 'X-ACCOUNT-ID: <YOUR_ACCOUNT_ID>'
```

--------------------------------

### Create a Pass via CLI

Source: https://www.passninja.com/documentation/sdks

Create a pass using the command line interface with either individual field flags or a JSON body.

```bash
passninja pass create <YOUR_TEMPLATE_ID> \
--field member.level=silver \
--field discount=50% \
--field member.name=John
```

```bash
passninja pass create <YOUR_TEMPLATE_ID> \
--data '{"member.level":"silver","discount":"50%","member.name":"John"}'
```

--------------------------------

### Authentication

Source: https://www.passninja.com/documentation/api-reference

Every API request must be authenticated using the X-API-KEY and X-ACCOUNT-ID headers.

```APIDOC
## Authentication

### Description
Every API request must be authenticated. We use two custom HTTP headers for authentication. The first is an API key, the second is an account ID - both of these can be found in your account dashboard under pass template "send" page for a given pass in the Pass Templates tab.

### Headers
- **X-API-KEY** (string) - Required - Your API key (e.g., 91dbb1e7af9c80aba6ed3f95a1545b4e)
- **X-ACCOUNT-ID** (string) - Required - Your unique account identifier (e.g., aid_0xa01)

### Security Note
You should only send traffic over HTTPs and do your best to keep your authentication credentials private.
```

--------------------------------

### POST /v1/readers/heartbeat

Source: https://www.passninja.com/documentation/api-reference

Reports hardware identity and liveness for readers with no vendor MDM.

```APIDOC
## POST /v1/readers/heartbeat

### Description
Reports hardware identity and liveness for readers with no vendor MDM.

### Method
POST

### Endpoint
https://api.passninja.com/v1/readers/heartbeat

### Parameters
#### Request Body
- **serial** (string) - Optional - Reader serial number
- **manufacturer** (string) - Optional - Reader manufacturer
- **model** (string) - Optional - Reader model
- **firmware** (string) - Optional - Firmware version
- **source** (string) - Optional - Source of the heartbeat

### Request Example
{
  "serial": "AJ00217043",
  "manufacturer": "Dot Origin",
  "model": "VTAP100-PRO-POE",
  "firmware": "2.10.1",
  "source": "cli-client"
}
```

--------------------------------

### POST /v1/passes/<YOUR_TEMPLATE_ID>/smarttap/presign

Source: https://www.passninja.com/documentation/api-reference

Generates terminal nonce and ephemeral key pair for Google Smart Tap sessions.

```APIDOC
## POST /v1/passes/<YOUR_TEMPLATE_ID>/smarttap/presign

### Description
Generates terminal nonce and ephemeral key pair for Google Smart Tap sessions.

### Method
POST

### Endpoint
https://api.passninja.com/v1/passes/<YOUR_TEMPLATE_ID>/smarttap/presign

### Parameters
#### Path Parameters
- **YOUR_TEMPLATE_ID** (string) - Required - The template ID to pair with the session.

### Response
#### Success Response (200)
- **terminalNonce** (string) - Hex nonce
- **terminalEphemeralPublicKey** (string) - Hex public key
- **terminalEphemeralPrivateKey** (string) - Hex private key
- **signature** (string) - Hex signature
- **keyVersion** (string) - Key version

#### Response Example
{
  "terminalNonce": "<HEX>",
  "terminalEphemeralPublicKey": "<HEX>",
  "terminalEphemeralPrivateKey": "<HEX>",
  "signature": "<HEX>",
  "keyVersion": "1"
}
```

--------------------------------

### POST /v1/webhooks

Source: https://www.passninja.com/documentation/api-reference

Creates a new webhook subscription and returns a bearer token for authentication.

```APIDOC
## POST /v1/webhooks

### Description
Creates a subscription and returns a freshly generated bearer token. The plaintext token is included in the response only on creation.

### Method
POST

### Endpoint
/v1/webhooks

### Request Body
- **name** (string) - Required - Human label, ≤ 120 chars.
- **url** (string) - Required - Absolute https:// URL.
- **subscribedEvents** (array) - Required - Non-empty array of CloudEvents type strings.
- **authMethod** (string) - Optional - Defaults to "bearer_token".
- **passTemplate** (string) - Optional - Scopes the subscription to one pass template.

### Request Example
{
  "name": "Production install handler",
  "url": "https://example.com/passninja/webhook",
  "subscribedEvents": ["pn.pass.installed", "pn.pass.uninstalled"]
}

### Response
#### Success Response (201)
- **id** (string) - Subscription ID
- **name** (string) - Human label
- **url** (string) - Webhook URL
- **authMethod** (string) - Authentication method
- **subscribedEvents** (array) - List of subscribed event types
- **passTemplate** (string) - Scoped pass template ID
- **active** (boolean) - Subscription status
- **createdAt** (string) - Creation timestamp
- **updatedAt** (string) - Update timestamp
- **bearerToken** (string) - Plaintext bearer token (only returned on creation)

#### Response Example
{
  "id": "47",
  "name": "Production install handler",
  "url": "https://example.com/passninja/webhook",
  "authMethod": "bearer_token",
  "subscribedEvents": ["pn.pass.installed", "pn.pass.uninstalled"],
  "passTemplate": null,
  "active": true,
  "createdAt": "2026-05-12T18:00:00.000Z",
  "updatedAt": "2026-05-12T18:00:00.000Z",
  "bearerToken": "wbk_b3d6…"
}
```
Tokens:
Raw