> ## Documentation Index
> Fetch the complete documentation index at: https://docs.passlet.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Base URL, authentication, scopes, and conventions for the Passlet public REST API.

The Passlet public API is a REST API for automating everything around passes: issuing and updating them, recording scans, managing projects and webhook endpoints, and reading template metadata.

```
Base URL: https://api.passlet.io
```

The full endpoint reference in the sidebar is generated from our OpenAPI 3.1 specification (downloadable at [`/api-reference/openapi.json`](/api-reference/openapi.json)), which is itself generated from the live route definitions — it cannot drift from the API's actual behaviour.

## Authentication

Every request needs an [access token](/developers/access-tokens) (`plt_…`), sent either way:

```bash theme={null}
# Authorization header (preferred)
curl https://api.passlet.io/v1/passes \
  -H "Authorization: Bearer $PASSLET_API_TOKEN"

# or X-API-Key header
curl https://api.passlet.io/v1/passes \
  -H "X-API-Key: $PASSLET_API_TOKEN"
```

Tokens belong to exactly one workspace — the API resolves your workspace from the token, so there is no workspace parameter anywhere. Requests without a valid token get `401 UNAUTHORIZED`; requests whose token lacks the operation's scope get `403 FORBIDDEN`.

### Scopes

Each operation requires a scope, documented on its endpoint page (and machine-readable as `x-required-scopes` in the spec): `passes:read`, `passes:write`, `templates:read`, `webhooks:read`, `webhooks:write`, `scans:read`, `scans:write`.

## Resources

| Resource              | What it covers                                                                   |
| --------------------- | -------------------------------------------------------------------------------- |
| **Passes**            | Issue (single/batch), read, void (single/batch), revoke add-to-wallet links      |
| **Templates**         | List templates, fetch the published version and its variables schema             |
| **Template versions** | List and read immutable published versions                                       |
| **Projects**          | CRUD plus per-project statistics                                                 |
| **Scans**             | Record (single/bulk), list, read, reverse, aggregate stats, real-time SSE stream |
| **Webhooks**          | Endpoint CRUD, test events, delivery history, redelivery                         |

## Conventions

* **JSON everywhere** — request and response bodies are `application/json` (UTF-8).
* **IDs** are opaque strings; don't parse them.
* **Timestamps** are ISO 8601 / RFC 3339 in UTC.
* **Idempotent issuance** — `externalPassId` is unique per workspace; re-sending a create with
  the same external ID doesn't create a duplicate pass.
* **Async lifecycle** — issuing, updating, and voiding are queued and processed in the
  background; the API returns immediately with the pass in its transitional status. Subscribe
  to [webhooks](/developers/webhooks) rather than polling.
* **Errors** — a stable machine-readable shape with `errorCode`, `message`, and
  `correlationId`; see [Errors](/api-reference/errors).
* **Pagination & filtering** — cursor-based, with one consistent filter grammar across list
  endpoints; see [Pagination & filtering](/api-reference/pagination-and-filtering).