PassFast

Generate a wallet pass Generates a wallet pass from a published template. For Apple passes (default), returns a signed `.pkpass` binary file directly. For Google passes (`wallet_type: "google"`), returns a JSON object containing a `save_url` that the user can open to add the pass to Google Wallet. When `wallet_type: "both"`, generates both Apple and Google passes in a single call. The response is always JSON with `apple` and `google` keys. Partial success is allowed — if one wallet fails, the other is still returned with a warning. Returns 201 if at least one succeeds. The pass ID is returned in the `X-Pass-Id` response header (for single-wallet). If the app has a validation webhook configured, the webhook is called once before generation (not per wallet type). A webhook rejection returns 403; a webhook error returns 502 (fail-closed). **Scope:** `passes:create` Maps to OpenAPI operationId `generatePass` — POST /generate-pass. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Batch generate limits Public metadata for `POST /passes/batch`. No authentication. Returns the hard row cap (100), sync mode, auth summary, and stable error codes. This path is on the site host (`https://passfa.st/api`), not `https://api.passfa.st/functions/v1`. MCP tool: `getBatchGenerateLimits`. Maps to OpenAPI operationId `getBatchGenerateLimits` — GET /passes/batch. Public endpoint — no API key required. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

无需输入参数。

Batch generate wallet passes Generate up to 100 wallet passes in one **synchronous** request. Each accepted row is one `POST /generate-pass` (same free-100 and card-on-file gates as a single generate). Optional `POST /share-pass/create` per successful row when `create_share_links` is true (default). **Host:** `https://passfa.st/api/passes/batch` (site / Vercel preview). This is not an `api.passfa.st` Edge Function. MCP tool: `batchGeneratePasses` (secret key `sk_live_` only) — same path and body as this operation. **Auth:** `Authorization: Bearer sk_live_…` or `pk_live_…` (scope `passes:create`). A Supabase user JWT is also accepted (dashboard session). Send `X-App-Id` for multi-app orgs and `X-Org-Id` as elsewhere. **Body:** mapped `rows` (same shape the dashboard posts) **or** raw `csv` plus optional `column_map`. Do not send both. **Limits:** more than 100 rows → `400 row_limit_exceeded` **before** any generate. Empty body / empty CSV → `400 empty_batch` or `invalid_csv`. Bad template → `400 invalid_template`. Missing or invalid Bearer → `401 unauthorized`. **Billing:** a row that hits the free-100 / card gate returns the same `402` codes as generate-pass (`free_limit_reached`, `subscription_canceled`, `payment_past_due`). Remaining rows stop. Already-created rows stay. HTTP `402` is returned only when **zero** rows succeeded; a later-row 402 after some successes is HTTP `200` with `stopped_reason` and per-row results. **Partial failures:** other per-row errors (validation, duplicate serial, share-link warning) continue. The response lists every processed row. **Scope:** `passes:create` Maps to OpenAPI operationId `batchGeneratePasses` — POST /passes/batch. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

List passes Returns a paginated list of passes for the current app. **Scope:** `passes:read` Maps to OpenAPI operationId `listPasses` — GET /manage-passes. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Get a pass Returns the full details of a single pass. **Scope:** `passes:read` Maps to OpenAPI operationId `getPass` — GET /manage-passes/{id}. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Update a pass Updates the dynamic data of an active pass. Optionally sends a push notification to registered devices so they fetch the updated pass. At least one of `data`, `expires_at`, `locations`, `relevant_date`, or `max_distance` is required. **Scope:** `passes:manage` Maps to OpenAPI operationId `updatePass` — PATCH /manage-passes/{id}. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Get a pass by serial number Returns the full details of a single pass looked up by serial number. When a serial has both Apple and Google passes, use `?wallet_type=` to select which one (defaults to `apple`). **Scope:** `passes:read` Maps to OpenAPI operationId `getPassBySerial` — GET /manage-passes/serial/{serial_number}. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Update a pass by serial number Updates the dynamic data of an active pass looked up by serial number. Optionally sends a push notification to registered devices. At least one of `data`, `expires_at`, `locations`, `relevant_date`, or `max_distance` is required. When a serial has both Apple and Google passes, use `?wallet_type=` to select which one (defaults to `apple`). **Scope:** `passes:manage` Maps to OpenAPI operationId `updatePassBySerial` — PATCH /manage-passes/serial/{serial_number}. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Download a .pkpass file by serial number Downloads the `.pkpass` binary for an active pass looked up by serial number. When a serial has both Apple and Google passes, use `?wallet_type=` to select which one (defaults to `apple`). **Scope:** `passes:download` Maps to OpenAPI operationId `downloadPassBySerial` — GET /manage-passes/serial/{serial_number}/download. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Void a pass by serial number Marks a pass (looked up by serial number) as invalidated and rebuilds the `.pkpass` file with Apple's `voided: true` flag. Registered devices are sent push notifications so the pass appears voided immediately in Apple Wallet. When a serial has both Apple and Google passes, use `?wallet_type=` to select which one (defaults to `apple`). **Scope:** `passes:manage` Maps to OpenAPI operationId `voidPassBySerial` — POST /manage-passes/serial/{serial_number}/void. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Download a .pkpass file Downloads the `.pkpass` binary for an active pass. **Scope:** `passes:download` Maps to OpenAPI operationId `downloadPass` — GET /manage-passes/{id}/download. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Void a pass Marks a pass as invalidated and rebuilds the `.pkpass` file with Apple's `voided: true` flag. Registered devices are sent push notifications so the pass appears voided immediately in Apple Wallet. Rebuild failure is non-fatal — the pass is still invalidated at the DB level. **Scope:** `passes:manage` Maps to OpenAPI operationId `voidPass` — POST /manage-passes/{id}/void. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Create a template Creates a new pass template in draft status. **Scope:** `templates:manage` Maps to OpenAPI operationId `createTemplate` — POST /manage-templates. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

List templates Returns all templates for the current app. By default returns non-archived templates. Set `archived=true` to return only archived templates. **Scope:** `templates:manage` Maps to OpenAPI operationId `listTemplates` — GET /manage-templates. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Get a template Returns the full details of a single template. **Scope:** `templates:manage` Maps to OpenAPI operationId `getTemplate` — GET /manage-templates/{id}. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Update a template Updates a draft template. Published templates cannot be modified. **Scope:** `templates:manage` Maps to OpenAPI operationId `updateTemplate` — PATCH /manage-templates/{id}. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Delete a template Soft-deletes a template by marking it as archived. Use `permanent=true` to permanently delete the template and its associated data. **Scope:** `templates:manage` Maps to OpenAPI operationId `deleteTemplate` — DELETE /manage-templates/{id}. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Publish a template Publishes a draft template, making it available for pass generation. Published templates cannot be modified. **Scope:** `templates:manage` Maps to OpenAPI operationId `publishTemplate` — POST /manage-templates/{id}/publish. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Upload an image Uploads an image for use in pass templates or per-pass strip overrides. Send as multipart form data with a `purpose` field and a `file` field containing the PNG image. **Upload behaviour by purpose:** - `strip` — **accumulates**. Each upload creates a new image; the returned `id` can be passed as `strip_image_id` on `POST /v1/passes` or `PATCH /v1/passes/{id}` to give individual passes their own banner. Previous `strip` images are NOT deleted — manage them via `DELETE /v1/images/{id}` when no longer referenced. - All other purposes (`icon`, `logo`, `thumbnail`, `background`, `footer`, and all `_2x`/`_3x` variants) — **replace-on-upload**. Uploading a new image of the same purpose deletes the previous one from storage and DB. These are app-wide template assets, not per-pass. **Scope:** `images:manage` Maps to OpenAPI operationId `uploadImage` — POST /manage-images. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

List images Returns all images for the current app, including signed preview URLs. **Scope:** `images:manage` Maps to OpenAPI operationId `listImages` — GET /manage-images. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Delete an image Deletes an image (storage file + DB row). Always succeeds when the image exists. Any template column pointing at this image is silently cleared (the template falls back to no image in that slot — re-attach a new one if needed). Any pass with `strip_image_id` pointing at this image has its override nullified and reverts to the template's strip on next render. Use `GET /manage-images/{id}/usage` first if you need to know the blast radius before deleting. **Scope:** `images:manage` Maps to OpenAPI operationId `deleteImage` — DELETE /manage-images/{id}. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Get image usage / reference counts Report how an image is referenced across templates and passes. Useful before DELETE to confirm an image is unused, or to find which templates a shared asset is attached to. - `template_refs` lists every template column (e.g. `strip_image_id`, `icon_image_id`, `google_logo_image_id`) that references this image. - `pass_refs_count` is the number of passes whose per-pass `strip_image_id` points at this image. - `safe_to_delete` is `true` when `total_refs` is 0. **Scope:** `images:manage` Maps to OpenAPI operationId `getImageUsage` — GET /manage-images/{id}/usage. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Upload a .p12 certificate bundle Uploads a PKCS#12 (.p12) bundle containing signer certificate and private key. The bundle is decrypted with the provided password, and individual certificates are extracted and stored with AES-256-GCM encryption. **Scope:** `certs:manage` Maps to OpenAPI operationId `uploadP12Certificate` — POST /manage-certs/p12. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Upload a single certificate Uploads a single PEM-encoded certificate or key. **Scope:** `certs:manage` Maps to OpenAPI operationId `uploadCertificate` — POST /manage-certs. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

List certificates Returns all certificates for the current app. **Scope:** `certs:manage` Maps to OpenAPI operationId `listCertificates` — GET /manage-certs. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Delete a certificate Deletes a certificate. **Scope:** `certs:manage` Maps to OpenAPI operationId `deleteCertificate` — DELETE /manage-certs/{id}. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Upload Google credentials Uploads Google service account credentials for Google Wallet pass signing. The service account JSON and issuer ID are stored securely. **Scope:** `certs:manage` Maps to OpenAPI operationId `uploadGoogleCredentials` — POST /manage-certs/google. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

List Google credentials Returns all active Google Wallet credentials for the current app. **Scope:** `certs:manage` Maps to OpenAPI operationId `listGoogleCredentials` — GET /manage-certs/google. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Deactivate Google credential Deactivates a Google Wallet credential. **Scope:** `certs:manage` Maps to OpenAPI operationId `deactivateGoogleCredential` — DELETE /manage-certs/google/{id}. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Test Google connection Tests the configured Google Wallet credentials by attempting to authenticate with the Google Wallet API. **Scope:** `certs:manage` Maps to OpenAPI operationId `testGoogleConnection` — POST /manage-certs/google/test. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Test Apple certificates Generates an ephemeral test `.pkpass` file to verify that the uploaded Apple signing certificates are valid and complete. The test pass is not stored — it is returned directly as a binary download. **Scope:** `certs:manage` Maps to OpenAPI operationId `testAppleCertificates` — POST /manage-certs/test. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Get organization details Returns the current organization's settings. **Scope:** `org:read` Maps to OpenAPI operationId `getOrganization` — GET /manage-org. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

无需输入参数。

Update organization settings Updates the current organization's settings, including APNs credentials. **Scope:** `org:manage` Maps to OpenAPI operationId `updateOrganization` — PATCH /manage-org. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Get current app details Returns the current app's settings. **Scope:** `org:read` Maps to OpenAPI operationId `getApp` — GET /manage-org/app. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Create a new app Creates a new app within the organization. **Scope:** `org:manage` Maps to OpenAPI operationId `createApp` — POST /manage-org/app. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Update app settings Updates the current app's settings, including webhook configuration. Set `regenerate_webhook_secret` to `true` to generate a new webhook signing secret; the new secret is returned in `webhook_secret_raw` (shown only once). **Scope:** `org:manage` Maps to OpenAPI operationId `updateApp` — PATCH /manage-org/app. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Deactivate an app Deactivates the current app. This does not permanently delete data. **Scope:** `org:manage` Maps to OpenAPI operationId `deleteApp` — DELETE /manage-org/app. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Test the validation webhook Sends a sample validation webhook payload to the configured URL and returns the result. **Scope:** `org:manage` Maps to OpenAPI operationId `testWebhook` — POST /manage-org/app/test-webhook. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Check managed signing availability Returns whether managed (platform) signing credentials are available for Apple and Google wallets. When `apple_ready` or `google_ready` is `true`, apps can use `signing_mode: "managed"` or `google_signing_mode: "managed"` without uploading their own credentials. **Scope:** `org:read` Maps to OpenAPI operationId `getManagedSigningStatus` — GET /manage-org/managed-signing-status. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

无需输入参数。

List webhook events Returns a paginated list of webhook event delivery records for the current app. **Scope:** `org:read` Maps to OpenAPI operationId `listWebhookEvents` — GET /manage-org/webhook-events. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

List API keys Returns all API keys for the current organization. **Scope:** `org:manage` Maps to OpenAPI operationId `listApiKeys` — GET /manage-keys. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

无需输入参数。

Create an API key Creates a new API key. The response contains `id`, `name`, `key_type`, `key_prefix`, `raw_key`, and `message`. The full raw key is shown only once and cannot be retrieved again. **Scope:** `org:manage` Maps to OpenAPI operationId `createApiKey` — POST /manage-keys. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Revoke an API key Revokes an API key, making it inactive. Revoked keys cannot authenticate. **Scope:** `org:manage` Maps to OpenAPI operationId `revokeApiKey` — PATCH /manage-keys/{id}. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Delete an API key Permanently deletes an API key. The key **must be revoked first** (via PATCH) before it can be deleted. Attempting to delete an active key returns 400. **Scope:** `org:manage` Maps to OpenAPI operationId `deleteApiKey` — DELETE /manage-keys/{id}. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Create a share token Creates a public share token for a pass, enabling distribution via URL, QR code, or messaging. The share URL points to a public page where recipients can add the pass to Apple or Google Wallet without logging in. Idempotent — if the pass already has a share token, the existing token is returned (200) instead of creating a new one (201). For dual-wallet passes (same serial number with both Apple and Google), the share token is automatically applied to all sibling passes. **Scope:** `passes:manage` Maps to OpenAPI operationId `createShareToken` — POST /share-pass/create. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Get shared pass metadata Returns public metadata for a shared pass. No authentication required. Used by the public share page to display wallet buttons and pass info. Maps to OpenAPI operationId `getSharePassMetadata` — GET /share-pass/{token}. Public endpoint — no API key required. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.

Download shared Apple .pkpass Downloads the Apple `.pkpass` file for a shared pass. No authentication required. Only works for active Apple passes. Maps to OpenAPI operationId `downloadSharedPass` — GET /share-pass/{token}/download. Public endpoint — no API key required. Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.