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

# Introduction

> What the Voucher Platform partner integration is and how the pieces fit together.

This guide walks your engineering team through everything needed to integrate
your native app with the Voucher Platform: user provisioning, authentication,
the embeddable webview, the consumer API surface, and the outbound webhook
contract.

<Tip>
  For an interactive endpoint reference with try-it-out controls, switch to
  the **API Reference** tab in the top nav. The raw OpenAPI 3.1 spec is
  available at [`/openapi.json`](/openapi.json) — import it into Postman,
  Insomnia, or your codegen tool of choice.
</Tip>

<Note>
  **Stuck? Ask the [Partner Assistant](https://vouchers.hextar.com/assistant).**
  It's an AI chat grounded in these docs — handy for "what header do I send
  for X?" or "why am I getting `signature_expired`?" If it can't answer,
  email [albert.chai@hextar.com](mailto:albert.chai@hextar.com).
</Note>

## Three integration surfaces

There are exactly three surfaces partners touch:

<CardGroup cols={3}>
  <Card title="Server → us" icon="server" href="/surfaces/server-to-server">
    Your backend authenticates with HMAC; you upsert and delete users at `/integrations/*`.
  </Card>

  <Card title="Webview / consumer" icon="mobile" href="/surfaces/webview">
    Runs inside the partner-issued webview (or your own UI); authenticates with the per-user JWT you mint.
  </Card>

  <Card title="Outbound webhooks" icon="webhook" href="/webhooks/overview">
    We POST signed JSON to your `webhookUrl` whenever a user event happens.
  </Card>
</CardGroup>

## How the pieces fit together

```
┌─────────────────────┐   1. POST /integrations/users      ┌──────────────────────┐
│                     ├───────────────────────────────────▶│                      │
│  Your backend       │   2. mint JWT for user             │  Voucher Platform    │
│                     │                                    │                      │
│                     │◀───────────────────────────────────┤                      │
│                     │   5. webhook on claim/redemption   │                      │
└──────────┬──────────┘                                    └──────────▲───────────┘
           │                                                          │
           │ 3. open /consumer#token=<JWT>                            │
           ▼                                                          │
┌─────────────────────┐                                               │
│                     │   4. user claims & redeems vouchers           │
│  Embedded webview   ├───────────────────────────────────────────────┘
│  (in your app)      │
└─────────────────────┘
```

<Note>
  **Step 1 is optional.** If you skip the explicit user upsert, the user is
  created just-in-time the first time their JWT arrives at `/me`. Most
  partners still call `POST /integrations/users` so PII corrections (email
  changes, opt-outs) propagate without waiting for the next webview open.
</Note>

## Where to start

<CardGroup cols={2}>
  <Card title="Quickstart" icon="play" href="/quickstart">
    End-to-end worked example: provision a user, mint a JWT, open the webview, receive the webhook.
  </Card>

  <Card title="Concepts" icon="book-open" href="/concepts/overview">
    Vocabulary and the mental model. Read this first if you're new to the integration.
  </Card>
</CardGroup>