> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/developers-guides/readme.md).

# The Wallet Crew API developer guide

Build Apple Wallet and Google Wallet pass integrations with The Wallet Crew API, including authentication, pass updates, webhooks, scans, and reporting.

## The Wallet Crew API developer guide

Build Apple Wallet and Google Wallet pass integrations with The Wallet Crew. This guide covers API authentication, pass updates, webhooks, scans, reporting, and the paths that support each workflow.

<a href="https://docs.thewalletcrew.io/api-reference/" class="button primary" data-icon="terminal">Open API reference</a>

<details>

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

* Create a loyalty pass after signup or checkout.
* Update pass fields after a CRM, ticketing, or POS event.
* Forward wallet lifecycle events to a backend, CRM, or analytics stack.

</details>

### Start here

Most developer projects follow the same path.

{% stepper %}
{% step %}

#### Get credentials

Generate an API key from the admin console, in **Settings → Security → API Keys**. Send it in the `X-API-KEY` header on every request.
{% endstep %}

{% step %}

#### Open the API reference

Use the API reference to inspect endpoints, request bodies, response schemas, permissions, and live examples.

[Open API reference](https://docs.thewalletcrew.io/api-reference/)
{% endstep %}

{% step %}

#### Make a first request

Start with a pass that already exists rather than a creation flow. This is the fastest way to validate tenant access, authentication, and update behavior without mixing creation logic into the first test.

The most common first call is a forced pass update. It tells the platform to re-fetch data from configured providers, rebuild the pass, and push the updated version to the device:

```http
PATCH /api/{tenantId}/passes?id={passId}
X-API-KEY: {api_key}
Content-Type: application/json

{
  "additionalData": { "loyaltyTier": "gold" },
  "options": { "updateMetadata": true }
}
```

A pass can also be targeted by an external identifier instead of `passId`, for example `id.shopify.customerId={customerId}`. See Key concepts for the difference between the two. A `200` response means the update ran synchronously; `202` means it was queued.

If no pass exists yet, start with Enrolment flows or Connector-triggered pass creation instead, then come back to this call once a pass is issued.

Continue with [Getting started with the API](/developers-guides/integration-guides/getting-started-with-the-api.md) for the full walkthrough.
{% endstep %}

{% step %}

#### Expand the integration

Once the first management call works, move to creation flows, updates, webhooks, scans, and reporting.
{% endstep %}
{% endstepper %}

### Authentication

Some tenant-scoped APIs support other authentication models or extra scopes, for example the OAuth2 flow used by certain administrative operations. When that applies, the endpoint guide or the API reference is the source of truth.

{% hint style="info" %}
For a first integration, start with APIs documented around `X-API-KEY`. This is the usual path for pass management, webhooks, scans, and the interactive API reference.
{% endhint %}

### API reference

Use the API reference when the exact payload shape, response schema, or endpoint behavior matters.

[Open API reference](https://docs.thewalletcrew.io/api-reference/)

### Developer guides

These guides cover the main integration patterns.

* [Key concepts](/developers-guides/readme/key-concepts.md) covers tenants, identifiers, templates, and pass lifecycle basics.
* [Getting started with the API](/developers-guides/integration-guides/getting-started-with-the-api.md) walks through the first tenant-scoped request.
* [Enrolment flows](/developers-guides/integration-guides/wallet/enrolment-flows.md) and [Connector-triggered pass creation](/developers-guides/integration-guides/wallet/connector-triggered-pass-creation.md) cover new-pass issuance.
* [Update pass data in templates](/developers-guides/integration-guides/wallet/update-pass-data-in-templates.md) explains how to render current pass data.
* [Webhooks](/developers-guides/integration-guides/webhooks.md), [Scan API](/developers-guides/integration-guides/scan-api.md), and [Insights API](/developers-guides/integration-guides/insights-api.md) cover events, scans, and reporting.

### Common next steps

After the first request succeeds, the next step usually depends on the integration goal.

* If passes already exist, start with [Getting started with the API](/developers-guides/integration-guides/getting-started-with-the-api.md).
* If issuance starts in a signup, checkout, or hosted form, use [Enrolment flows](/developers-guides/integration-guides/wallet/enrolment-flows.md).
* If issuance starts from a source-system event, use [Connector-triggered pass creation](/developers-guides/integration-guides/wallet/connector-triggered-pass-creation.md).
* To keep wallet content current, use [Update pass data in templates](/developers-guides/integration-guides/wallet/update-pass-data-in-templates.md).
* To notify external systems in real time, use [Webhooks](/developers-guides/integration-guides/webhooks.md).

### FAQ

<details>

<summary><strong>How do I create an API key?</strong></summary>

Generate an API key from the admin console, then send it in `X-API-KEY` for the main platform APIs described in Start here.

</details>

<details>

<summary><strong>How should an API key be stored?</strong></summary>

Keep API keys in server-side secret storage. Do not expose them in browser code, mobile applications, logs, or source control.

</details>

<details>

<summary><strong>Where is the API reference?</strong></summary>

Use [API reference](https://docs.thewalletcrew.io/api-reference/) for the main API entry point.

</details>

<details>

<summary><strong>What is the best first API call?</strong></summary>

A forced update on an existing pass is usually the best first call because it validates tenant access, authentication, and the update path without depending on a creation flow.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thewalletcrew.io/developers-guides/readme.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.