# PassFast API

> Agent-readable overview of the PassFast HTTP API. Generate Apple Wallet
> and Google Wallet passes from a published template.

This file summarizes authentication, the base URL, and the key endpoints.
It is **not** a second contract. Paths, request bodies, and errors are
defined only in https://passfa.st/openapi.yaml. Narrative docs:
https://passfa.st/docs.md. HTML API Reference: https://passfa.st/docs.

- Site: https://passfa.st
- API host: https://api.passfa.st
- API base: https://api.passfa.st/functions/v1
- Sign up (get keys): https://passfa.st/signup
- TypeScript SDK: `npm install @passfast/sdk`
- MCP: https://passfa.st/docs/mcp · https://passfa.st/mcp.md

Last updated: 2026-09-20

## Base URL

All paths below are relative to:

```
https://api.passfa.st/functions/v1
```

## Authentication

PassFast uses two types of API keys. Manage them on the API Keys page after
signup. All keyed requests use a Bearer token:

```
Authorization: Bearer sk_live_your_secret_key_here
```

| Key type | Prefix | Use case | Scopes |
| --- | --- | --- | --- |
| Secret | `sk_live_` | Server-side only. Full API access. | All |
| Publishable | `pk_live_` | Client-side (browser). Can only generate and download passes. | `passes:create`, `passes:download` |

If the organization has multiple apps, include `X-App-Id` to target a
specific app. For single-app orgs this header is optional:

```
Authorization: Bearer sk_live_...
X-App-Id: YOUR_APP_ID
```

Do not put `sk_live_` keys in browsers or mobile apps. Member-management
endpoints use a Supabase JWT instead of API keys (see OpenAPI).

## Key endpoints

### Generate

| Method | Path | Summary |
| --- | --- | --- |
| POST | `/generate-pass` | Generate Apple Wallet, Google Wallet, or both |

Scope: `passes:create`. The template must be published first.

### Manage passes

| Method | Path | Summary |
| --- | --- | --- |
| GET | `/manage-passes` | List passes |
| GET | `/manage-passes/{id}` | Get a pass |
| PATCH | `/manage-passes/{id}` | Update a pass (triggers wallet push) |
| GET | `/manage-passes/{id}/download` | Download Apple `.pkpass` |
| POST | `/manage-passes/{id}/void` | Void a pass |
| GET | `/manage-passes/serial/{serial_number}` | Get by serial |
| PATCH | `/manage-passes/serial/{serial_number}` | Update by serial |
| GET | `/manage-passes/serial/{serial_number}/download` | Download by serial |
| POST | `/manage-passes/serial/{serial_number}/void` | Void by serial |

### Templates

| Method | Path | Summary |
| --- | --- | --- |
| GET | `/manage-templates` | List templates |
| POST | `/manage-templates` | Create a template |
| GET | `/manage-templates/{id}` | Get a template |
| PATCH | `/manage-templates/{id}` | Update a template |
| DELETE | `/manage-templates/{id}` | Delete a template |
| POST | `/manage-templates/{id}/publish` | Publish a template (required before generate) |

### Share

| Method | Path | Summary |
| --- | --- | --- |
| POST | `/share-pass/create` | Create a public share token |
| GET | `/share-pass/{token}` | Public share metadata (no auth) |
| GET | `/share-pass/{token}/download` | Public Apple `.pkpass` download |

Images, certificates, organization, API keys, members, and webhook events
are documented in https://passfa.st/openapi.yaml and listed in
https://passfa.st/docs.md.

## Generate a pass (curl)

Before you begin: an API key, a published template, and signing credentials
(managed signing is the default; custom Apple `.p12` / Google service-account
credentials are optional).

Both wallets (recommended):

```
curl -X POST https://api.passfa.st/functions/v1/generate-pass \
  -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY" \
  -H "X-App-Id: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "YOUR_TEMPLATE_ID",
    "serial_number": "PASS-001",
    "wallet_type": "both",
    "data": {
      "memberName": "Jane Smith",
      "memberId": "MEM-12345"
    }
  }'
```

Example JSON response (`wallet_type: "both"`):

```
{
  "apple": {
    "id": "uuid",
    "serial_number": "PASS-001",
    "wallet_type": "apple",
    "status": "active",
    "download_url": "/manage-passes/<id>/download"
  },
  "google": {
    "id": "uuid",
    "serial_number": "PASS-001",
    "wallet_type": "google",
    "status": "active",
    "save_url": "https://pay.google.com/gp/v/save/...",
    "google_object_id": "issuerId.passId"
  },
  "warnings": []
}
```

Use `wallet_type: "both"` to generate Apple and Google in one call. For
Apple-only, omit `wallet_type` (defaults to `"apple"`) and pipe to
`--output pass.pkpass`. For Google-only, set `wallet_type: "google"`.

### Request body (`POST /generate-pass`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `template_id` | string | Yes | ID of a published template |
| `serial_number` | string | Yes | Unique serial number for this pass |
| `data` | object | Yes | Dynamic values matching the template's field schema |
| `wallet_type` | string | No | `"both"` (recommended), `"apple"` (default), or `"google"` |
| `external_id` | string | No | Your own identifier for cross-referencing |
| `expires_at` | string | No | ISO 8601 expiration date |
| `get_or_create` | boolean | No | Return existing active pass instead of 409 on duplicate serial (default: false) |

Additional generate-pass fields (locations, images, and others) are in
https://passfa.st/openapi.yaml only.

## TypeScript SDK

```
npm install @passfast/sdk
```

```
import { PassFast } from "@passfast/sdk";

const pf = new PassFast("sk_live_YOUR_SECRET_KEY");

const { passId, pkpassData } = await pf.passes.generate({
  template_id: "YOUR_TEMPLATE_ID",
  serial_number: "PASS-001",
  data: { memberName: "Jane Smith", memberId: "MEM-12345" },
});
```

## MCP

Remote HTTPS MCP at https://passfa.st/mcp (alias `/api/mcp`). Tools are
named after these OpenAPI `operationId`s. Paste `sk_live_…` once in the
MCP client — no OAuth. This server accepts only a secret key. Install:
https://passfa.st/docs/mcp · https://passfa.st/mcp.md

Member/invite operations are JWT-only and **out of scope for key-auth MCP v1**.

## Canonical spec

https://passfa.st/openapi.yaml is the only API surface. Use it for every
path, body, header, scope, and error. This markdown file and
https://passfa.st/docs.md are readable summaries.

## Related

- Docs (markdown): https://passfa.st/docs.md
- Docs (HTML): https://passfa.st/docs
- MCP (HTML): https://passfa.st/docs/mcp
- MCP (markdown): https://passfa.st/mcp.md
- Pricing (markdown): https://passfa.st/pricing.md
- Pricing (HTML): https://passfa.st/#pricing
- AI index: https://passfa.st/llms.txt
- Full AI index: https://passfa.st/llms-full.txt
- Privacy: https://passfa.st/privacy
- Terms: https://passfa.st/terms