Overview
Passinstance supports exporting and importing complete template definitions as structured, portable JSON files. This capability enables:
-
Environment Migration: Promoting tested pass templates from a
sandboxworkspace to aproductionworkspace without manual recreation. -
Backup & Disaster Recovery: Storing canonical template configurations in Git repositories or version control systems (Configuration as Code).
-
Template Sharing & Cloning: Distributing standardized loyalty, ticket, or membership layouts across distinct client accounts or franchise operators.
Exported files use the canonical Passinstance export specification (TEMPLATE_EXPORT_FORMAT = 'passinstance-template', schema version 1) implemented in template-import-export.util.ts. System identifiers, database primary keys, tenant IDs, and cryptographic signing certificates are stripped automatically to guarantee multi-tenant security and prevent identity collisions.
System Architecture: Template Export & Import Workflow
The Passinstance Template Export Format Specification
The export generator (buildSanitizedTemplateExportPayload) outputs a standardized JSON envelope conforming to TEMPLATE_EXPORT_SCHEMA_VERSION = 1:
{
"format": "passinstance-template",
"version": 1,
"exportedAt": "2026-11-16T20:40:00.000Z",
"template": {
"name": "Artisan Coffee Club - Gold Tier",
"kind": "storeCard",
"organizationName": "Artisan Roasters",
"description": "Artisan Coffee Loyalty Card",
"colors": {
"backgroundColor": "rgb(20, 35, 28)",
"foregroundColor": "rgb(255, 255, 255)",
"labelColor": "rgb(167, 243, 208)",
"stripColor": "rgb(255, 255, 255)"
},
"barcode": {
"format": "PKBarcodeFormatQR",
"messageEncoding": "UTF_8",
"altText": "{cardNumber}",
"addSecurityAnimation": true
},
"fields": {
"headerFields": [
{
"key": "tier",
"label": "TIER",
"value": "Gold Member",
"textAlignment": "PKTextAlignmentRight"
}
],
"primaryFields": [
{
"key": "holder",
"label": "MEMBER",
"value": "{firstName} {lastName}"
}
],
"secondaryFields": [
{
"key": "balance",
"label": "POINTS BALANCE",
"value": "{pointsBalance}",
"numberStyle": "PKNumberStyleDecimal"
}
],
"auxiliaryFields": [
{
"key": "since",
"label": "MEMBER SINCE",
"value": "{memberSince}",
"dateStyle": "PKDateStyleMedium"
}
],
"backFields": [
{
"key": "terms",
"label": "TERMS & CONDITIONS",
"value": "Points are earned on every purchase. Terms subject to change."
}
]
},
"locations": [
{
"latitude": 52.520008,
"longitude": 13.404954,
"maxDistance": 150,
"relevantText": "Welcome to Artisan Roasters! Scan your card for points."
}
],
"sharing": {
"sharingProhibited": false
}
}
}
Security & Sanitization Invariants
To maintain strict tenant isolation and protect cryptographic assets, Passinstance enforces five core security invariants during export and import (template-import-export.util.ts:25-34):
1. System Key Stripping
The following keys are strictly stripped from export payloads and rejected during import:
-
Primary and foreign keys:
id,customerId,tenantId,baseId,groupId. -
Revision metadata:
versionNumber,version,rowKind,status. -
Passholder records:
passes,activePassesCount. -
Timestamps:
createdAt,updatedAt,archivedAt. -
Apple Developer identity:
teamIdentifier,passTypeIdentifier,certificateId.
2. Payload Size Limits
-
maximum upload size limit = 5 * 1024 * 1024(5 MB): Payloads exceeding 5 megabytes are rejected immediately with HTTP 413. -
MAX_ZIP_ENTRY_BYTES = 1 * 1024 * 1024(1 MB): For zipped packages, individual entries cannot exceed 1 MB. -
MAX_ZIP_ENTRIES = 250: Prevents zip bomb decompression attacks. -
MAX_PLIST_DEPTH = 32: Prevents recursive entity expansion.
3. Prototype Pollution Prevention
Any incoming JSON object containing __proto__, constructor, or prototype is flagged and sanitized before object construction.
Exporting a Template (Dashboard & REST API)
In the Dashboard
-
1
Open the template in the Visual Editor.
-
2
Click the More actions (...) menu in the top CommandBar.
-
3
Select Export as JSON.
-
4
The browser downloads
<template-slug>-export.jsonimmediately.
Via REST API
/api/v1/templates/:templateId/export?format=json
curl -X GET "https://api.passinstance.com/api/v1/templates/tmpl_01h9x8k7m6n5p4/export?format=json" \
-H "X-API-Key: <API_KEY>" \
-o template-export.json
Importing a Template (Dashboard & REST API)
1. Import as a New Template (POST /api/v1/templates/import)
Creates a completely new template in the destination workspace:
curl -X POST "https://api.passinstance.com/api/v1/templates/import" \
-H "X-API-Key: <API_KEY>" \
-H "Content-Type: application/json" \
-d @template-export.json
HTTP Response (201 Created)
{
"success": true,
"data": {
"id": "tmpl_new_destination_01",
"name": "Artisan Coffee Club - Gold Tier",
"kind": "storeCard",
"status": "PUBLISHED",
"versionNumber": 1,
"rowKind": "PRODUCTION",
"createdAt": "2026-11-16T20:45:00.000Z"
},
"statusCode": 201
}
2. Import into an Existing Draft (POST /api/v1/templates/:id/import-draft)
Updates the working DRAFT revision of an existing template without modifying live published passes:
curl -X POST "https://api.passinstance.com/api/v1/templates/tmpl_existing_01/import-draft" \
-H "X-API-Key: <API_KEY>" \
-H "Content-Type: application/json" \
-d @template-export.json
Troubleshooting Export & Import
| Symptom / Error | Root Cause | Resolution |
|---|---|---|
Unrecognized format identifier | JSON lacks "format": "passinstance-template" or uses unknown format. | Ensure the root JSON includes "format": "passinstance-template" and "version": 1. |
Payload exceeds 5MB limit | Large images or binary assets are embedded inside the JSON. | Remove raw base64 data and upload images through the asset management endpoint or dashboard UI. |
Certificate not assigned | Exported template does not carry signing certificates. | This is intentional. After importing, navigate to Template Settings and bind the target workspace's Apple and Google Wallet credentials. |
Next, explore Organize Templates & Passes to manage template catalogs, or read Template Versions & Publishing to promote imported drafts into production.
