Authentication

Overview

Zupy uses API key authentication for all partner API access. Each restaurant (company) you integrate with gets its own API key, provisioned by the Zupy team during onboarding.

One key per restaurant — if you integrate with 3 restaurants, you receive 3 API keys
No OAuth flows — authenticate once per request with a single header
No self-service — keys are provisioned by Zupy ops, not generated in a dashboard

API Key Format

All partner API keys follow this format:

zupy_pk_ + 32 alphanumeric characters

Example:

zupy_pk_abc123def456ghi789jkl012mno345pq

API keys are generated by the Zupy team and delivered to you during onboarding. You cannot create or rotate keys yourself.

Authentication Flow

Zupy provisions your key

During onboarding, the Zupy team creates your API key and assigns it to a specific restaurant (company). You also receive your webhook URL.

You receive credentials

You receive your zupy_pk_* API key, the company ID, and your integration slug (e.g., repediu).

Include X-API-Key in every request

Add the X-API-Key header to all API requests. No Authorization: Bearer — just the header and the key.

Making Authenticated Requests

Include your API key in the X-API-Key header on every request:

curl -X GET "https://api.zupy.com/api/v2/customers/?phone=5511987654321" \
  -H "X-API-Key: zupy_pk_your_api_key_here"

import requests

BASE_URL = "https://api.zupy.com/api/v2"
API_KEY = "zupy_pk_your_api_key_here"
HEADERS = {"X-API-Key": API_KEY}

response = requests.get(
    f"{BASE_URL}/customers/",
    params={"phone": "5511987654321"},
    headers=HEADERS,
)
print(response.json())

const BASE_URL = "https://api.zupy.com/api/v2";
const API_KEY = "zupy_pk_your_api_key_here";

const response = await fetch(
  `${BASE_URL}/customers/?phone=5511987654321`,
  { headers: { "X-API-Key": API_KEY } }
);
const data = await response.json();
console.log(data);

Access Levels

API keys have two access levels, configured by Zupy during onboarding:

Level	Can Do	Cannot Do
Read-only	Search customers, view points/rewards/coupons, list programs	Award points, redeem rewards, validate coupons
Read-write	Everything above + award points, redeem rewards, validate coupons	N/A

If you attempt a write operation with a read-only key, you receive a 403 Forbidden error.

Endpoint allowlist

Your partner API key can only reach the endpoints documented in this reference — the partner contract. Any other v2 endpoint (consumer, scanner, or internal endpoints) returns 403 Forbidden for a partner key, even though the same path may exist for the dashboard or mobile apps. This is a deliberate, fail-secure default: the partner surface equals exactly what is documented here, and new internal endpoints are never exposed to partner keys by accident.

403 — Endpoint not available to partner keys

{
  "type": "https://api.zupy.com/errors/permission-denied",
  "title": "Permission Denied",
  "status": 403,
  "detail": "This endpoint is not available to partner API keys."
}

Error Handling

All authentication errors follow the RFC 7807 Problem Details format.

{
  "type": "https://api.zupy.com/errors/authentication-required",
  "title": "Authentication Required",
  "status": 401,
  "detail": "Invalid API key"
}

{
  "type": "https://api.zupy.com/errors/permission-denied",
  "title": "Permission Denied",
  "status": 403,
  "detail": "Read-only API key cannot perform write operations"
}

{
  "type": "https://api.zupy.com/errors/permission-denied",
  "title": "Permission Denied",
  "status": 403,
  "detail": "Customer OTP verification required for this action"
}

{
  "type": "https://api.zupy.com/errors/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "Too many requests. Please retry after 30 seconds."
}

Rate Limits

API requests are rate-limited per API key. Your tier is assigned during onboarding.

Tier	Requests/min	Assigned To
Free	60	Default for new integrations
Standard	300	Active partners (e.g., Repediu, Saipos)
Enterprise	3,000	High-volume partners

Every response includes rate limit headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1711108800

The Retry-After header (seconds to wait) is only included in 429 responses. When you receive a 429, wait for the Retry-After duration before retrying.

OTP — Optional Per-Integration

OTP (One-Time Password) provides extra customer verification. OTP is NOT required for all partners — it depends on your integration’s trust level, configured by Zupy during onboarding.

Action	OTP Possible?	Depends On
Search customers	Never	—
View points balance/history	Never	—
Award points	Never	B2B operation
List rewards/coupons	Never	—
Redeem reward	Per config	`require_otp_for_redemption`
Validate/use coupon	Per config	`require_otp_for_coupon_usage`
Send webhook	Never	—

Partner examples

Partner	Enrollment OTP	Redemption OTP	Coupon OTP	Trust Partner	Rationale
Repediu	No	No	No	Yes	iFood/Rappi already verify customer identity
Goomer	No	Yes	Yes	No	Open tablet — customer types phone, no prior verification
Saipos	No	Yes	Yes	Yes	POS identifies customer, but coupon usage needs confirmation

If your integration requires OTP for certain actions, see the OTP Flow guide for the complete 3-step verification process.

Security Best Practices

Never expose API keys in frontend or client-side code. All API calls must go through your backend server.

Always use HTTPS — HTTP requests are rejected
Store keys in environment variables — never hardcode in source code

ZUPY_API_KEY=zupy_pk_your_api_key_here
ZUPY_BASE_URL=https://api.zupy.com/api/v2

import os

API_KEY = os.environ["ZUPY_API_KEY"]
BASE_URL = os.environ.get("ZUPY_BASE_URL", "https://api.zupy.com/api/v2")

const API_KEY = process.env.ZUPY_API_KEY;
const BASE_URL = process.env.ZUPY_BASE_URL || "https://api.zupy.com/api/v2";

One key per restaurant — do not share keys between companies
Contact Zupy immediately if you suspect a key has been compromised

Next Steps

Quick Start

Get your first API call working in under 15 minutes

Webhook Setup

Send order data to Zupy for automatic loyalty processing

OTP Flow

Implement customer identity verification when required

Introduction

Guides

Overview

API Key Format

Authentication Flow

Making Authenticated Requests

Access Levels

Endpoint allowlist

Error Handling

Rate Limits

OTP — Optional Per-Integration

Security Best Practices

Next Steps

Quick Start

Webhook Setup

OTP Flow

​Overview

​API Key Format

​Authentication Flow

​Making Authenticated Requests

​Access Levels

​Endpoint allowlist

​Error Handling

​Rate Limits

​OTP — Optional Per-Integration

​Security Best Practices

​Next Steps

Quick Start

Webhook Setup

OTP Flow

Overview

API Key Format

Authentication Flow

Making Authenticated Requests

Access Levels

Endpoint allowlist

Error Handling

Rate Limits

OTP — Optional Per-Integration

Security Best Practices

Next Steps