Onboarding & credentials

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.

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.

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.

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.

Get started

Concepts

Authentication

Integration surfaces

Webhooks

Reference