# API reference

All services exposed by The Wallet Crew platform are accessible through the API and documented in this API reference.

Endpoints are grouped by categories. Each category maps to a functional area of the platform, such as pass operations, customer profile operations, or tenant administration.

<details>

<summary><strong>Real-world examples</strong></summary>

* Create or update passes from a CRM, e-commerce platform, ticketing system, or POS.
* Register webhooks to sync events (pass created, installed, updated) to a data platform.
* Query adoption and usage through the Insights API (logs, events, metrics).
* Automate tenant administration tasks (users, roles, permissions) through API calls.

</details>

## OpenAPI specification

The Wallet Crew API definition follows the **OpenAPI specification**. The API reference is rendered from that OpenAPI definition and is the source of truth for endpoints, payloads, responses, scopes, and default throttling values.

{% hint style="info" %}
Adding “Open API reference” and “Download OpenAPI spec” buttons requires the target URLs for the selected environment.
{% endhint %}

## How the API reference is organized

The API reference groups endpoints by **tag**. In The Wallet Crew docs, each tag is treated as an API category.

The category list can evolve over time as new features are added. The intent stays stable: one category equals one clear product capability.

## API categories

The most common categories are listed below.

#### Passes

Endpoints used to create, read, update, and deactivate passes. This includes “Add to Wallet” related endpoints, and hosted views used in distribution flows.

Related guide: [How to Create Passes via API in The Wallet Crew](https://docs.thewalletcrew.io/develop/guides/wallet/how-to-create-passes-via-api-in-the-wallet-crew).

#### Customers

Endpoints used to create/update a customer profile, retrieve customer data, and (in some setups) authenticate customers for customer-scoped calls.

#### Webhooks

Endpoints used to register and manage webhook subscriptions, so external systems can receive real-time events from The Wallet Crew.

Related guide: [Webhook](https://docs.thewalletcrew.io/develop/guides/webhook).

#### Insights

Endpoints used to query usage data (logs, events, metrics). This API is typically used for reporting, monitoring, and analytics pipelines.

Related guide: [Insights API](https://docs.thewalletcrew.io/develop/guides/insights-api).

#### Tenant and administration

Endpoints used to manage tenant configuration and access control, such as users, roles, permissions, secrets, and system-level operations. These endpoints are usually restricted to admin identities and/or scoped API keys.

#### Utilities and content

Supporting endpoints used across multiple features, such as barcode generation, public asset retrieval, cached content, or email verification. Availability depends on tenant configuration and enabled modules.

## Authentication

The Wallet Crew APIs support two authentication methods:

#### OAuth 2.0 (Bearer token)

OAuth 2.0 is used for admin and user-based authentication flows. Calls use the standard HTTP header:

```http
Authorization: Bearer <access_token>
```

#### API key (`X-API-KEY`)

API keys are the simplest option for server-to-server calls (backend, integration middleware, scheduled jobs). Calls use the header:

```http
X-API-KEY: <api_key>
```

API keys are generated from the admin console. See [How to generate an API key](https://docs.thewalletcrew.io/configure/platform/api-key).

For the in-doc version of the same guide, see [API Key](https://docs.thewalletcrew.io/configure/platform/api-key).

{% hint style="warning" %}
API keys are secrets. They must stay server-side. They must not be embedded in mobile apps or front-end code.
{% endhint %}

## Tenant routing (`tenantId` in the URL)

All tenant-scoped endpoints include a `tenantId` path parameter. This is how requests are routed and isolated per tenant.

Typical pattern:

```http
/api/{tenantId}/...
```

Example:

```http
POST /api/{tenantId}/passes?passType={passType}
```

## Throttling and rate limits

API throttling is configurable per endpoint and per tenant. This protects the platform from abuse and helps prevent noisy-neighbor effects in a multi-tenant environment.

Default throttling values are documented in the API definition itself (OpenAPI). When a tenant uses custom throttling settings, the effective limit can differ from the documented default.

## Versioning and change policy

The Wallet Crew API does not use URL versioning (no `/v1`, `/v2`, …). The API is designed to remain stable over time.

When a breaking change is necessary, impacted brands are notified in advance. This notice includes the change scope, timeline, and mitigation steps.

## FAQ

<details>

<summary><strong>When to use OAuth 2.0 vs <code>X-API-KEY</code>?</strong></summary>

API keys are usually the default for backend integrations because they are easy to rotate and can be scope-restricted. OAuth 2.0 is typically used when calls are performed on behalf of an authenticated admin user or when an existing OAuth-based session already exists.

</details>

<details>

<summary><strong>Why is <code>tenantId</code> required in every URL?</strong></summary>

The platform is multi-tenant. The `tenantId` identifies which tenant owns the data and configuration used to process the request. It also enforces tenant isolation.

</details>

<details>

<summary><strong>Is there an API version to pin against?</strong></summary>

No. There is no URL versioning. Stability is handled through backward-compatible changes whenever possible, and direct notification when breaking changes are required.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.thewalletcrew.io/develop/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.