Zero-Knowledge Connect

Introduction

In the Zero-Knowledge model, partners integrate with the Funtrips API without sharing any personal customer data. Instead of sending identifiable information (such as email, name, or phone), the integrator generates their own external user identifier; a unique, opaque reference to their customer. This identifier is the only value exchanged between systems and is fully controlled by the integrator.

How it Works

The authentication flow mirrors the standard Authorization Flow, but uses the external identifier instead of a personal user profile:

sequenceDiagram
  title Zero-Knowledge Connect (no customer data shared)

  participant PBE as Partner Backend
  participant APP as Partner App (Mobile/Web)
  participant AUTH as Funtrips Auth
  participant API as Funtrips API

  Note over PBE,AUTH: 1) Backend auth (no PII)
  PBE->>AUTH: POST /oauth/token (grant_type=client_credentials)
  AUTH-->>PBE: backend_bearer (scoped JWT)

  Note over PBE,AUTH: 2) Create session with external_user_id
  PBE->>AUTH: POST /v1/session { external_user_id }
  AUTH-->>PBE: { one_time_code }

  Note over APP,AUTH: 3) Exchange code → public bearer (still no PII)
  APP->>AUTH: Open webframe with code<br/>OR POST /v1/oauth/token { code }
  AUTH-->>APP: public_bearer

  Note over APP,API: 4) Use public bearer for all user-facing APIs
  APP->>API: GET /v1/merchants, /products, /me/wallet, /checkouts…
  API-->>APP: Catalog / Balance / Checkout / Status

  Note over PBE,API: 5) Fulfillment without PII (keys only)
  PBE->>API: GET /v1/fulfillment?external_user_id=…
  API-->>PBE: Tickets / redemption data

1. Exchange Authorization Code → Public Bearer The integrator requests an authorization code for a given external user identifier. The code is then exchanged for a public bearer token.
2. Use the Public Bearer The bearer grants access to the same API routes as a standard integration — balance retrieval, wallet history, and ticket fulfillment — but without any customer attributes.
3. Retrieve Tickets and Balances Using the same external identifier, the integrator can retrieve the customer’s tickets, wallet entries, or other assets. This allows in-app display or sending confirmation emails directly from the integrator’s environment.

Why It Matters

This model offers complete data isolation:

• No personally identifiable information (PII) ever reaches Funtrips.
• Integrators retain full control and mapping of their customer records.
• The external identifier remains meaningful only within the partner’s own systems.

Advantages

• ✅ Zero customer data exchange — Only a non-identifying external key is used
• ✅ Full API compatibility — Works with all existing endpoints
• ✅ Secure and privacy-compliant — Meets GDPR and zero-knowledge design principles
• ✅ Minimal integration changes — Uses the same authorization and fulfillment flows