> ## 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.

# Onboarding & credentials

> Everything we issue at onboarding and how to handle each value.

Onboarding is a **two-way exchange**. Some values **we generate and issue to
you**; others **you provide to us** so we can verify your tokens and reach your
systems. The **Provided by** column below says exactly who owns each value.

| Credential                     | Provided by                                                                | Used for                                                                                                                                                     | Visibility                                            |
| ------------------------------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
| `partner_id` (UUID)            | **Voucher Platform** — auto-generated at creation                          | Identifies your account in admin views.                                                                                                                      | OK to log.                                            |
| `slug`                         | **Voucher Platform** — set at creation (you may request a preferred value) | Sent as `x-partner-slug` on every `/integrations/*` call.                                                                                                    | OK to log.                                            |
| **HMAC secret**                | **Voucher Platform** — auto-generated, shown **once**                      | Signs every `/integrations/*` request and verifies every webhook we send.                                                                                    | **Secret.** Store encrypted. Rotate via the admin UI. |
| `jwtIssuer`                    | **You (partner)** — you choose it, tell us                                 | The `iss` claim our verifier expects on your JWTs.                                                                                                           | OK to log.                                            |
| `jwtAudience`                  | **You (partner)** — optional                                               | If set, our verifier requires it in `aud`.                                                                                                                   | OK to log.                                            |
| `jwksUrl` *or* `jwtPublicKey`  | **You (partner)** — you host the JWKS endpoint, or hand us a static PEM    | How we fetch your JWT verification key. JWKS URL is recommended so you can rotate without telling us.                                                        | OK to log.                                            |
| `webhookUrl`                   | **You (partner)** — your endpoint                                          | Where we POST event notifications. HTTPS required in production. Private / loopback URLs are refused at dispatch time as an SSRF guard.                      | OK to log.                                            |
| `scopeMode`                    | **Voucher Platform** — set per agreement                                   | `ALL` (default) or `ALLOWLIST`. When `ALLOWLIST`, your users only see merchants explicitly linked to your partner record (plus optionally whole categories). | OK to log.                                            |
| `displayName` *and* `logoPath` | **You (partner)** — you supply the name + logo asset; we store it          | Brand block surfaced by `GET /me` so the webview can render your logo instead of ours.                                                                       | OK to log.                                            |

<Tip>
  **Rule of thumb.** We issue your **identity** (`partner_id`, `slug`) and the
  shared **HMAC secret**, and we set **`scopeMode`**. You provide everything we
  need to **trust your tokens** (`jwtIssuer` + `jwksUrl`/`jwtPublicKey`), to
  **reach you** (`webhookUrl`), and your **brand** (`displayName`, logo). Your
  JWT *private* signing key never leaves your backend — you never send it to us.
</Tip>

<Warning>
  **HMAC secret rotation.** From the admin UI you can issue a new secret
  while keeping the old one active for a grace window. During rotation, our
  verifier accepts multiple `v1=` entries — sign requests with both old and
  new keys until you've finished the cutover.
</Warning>

<Note>
  **`hmacSecret` is dual-purpose.** The same secret signs your inbound
  `/integrations/*` requests **and** our outbound webhooks to your
  `webhookUrl`. There is no second "webhook secret" to manage — rotate the
  HMAC secret and both directions roll over together.
</Note>