Authentication & Multi-Tenancy

All requests to the HeyPeppy API must be authenticated using an API key passed in the standard Authorization HTTP header.

Authorization: Bearer hp_live_your_api_key_here
X-Tenant-ID: your_tenant_id

Requests made without an Authorization header, or with an invalid key, will return an HTTP 401 Unauthorized status.

---

Multi-Tenancy & Tenant Resolution

HeyPeppy is architected as a fully isolated multi-tenant platform. Each B2B partner account is assigned a unique tenantId (e.g. stepup, odyssey, classwallet, partner_demo).

Specifying Tenant Context

You can specify the tenant in one of two ways:

1. HTTP Header (Recommended):

   X-Tenant-ID: your_tenant_id

2. Request Body Property:

   {
     "tenantId": "your_tenant_id",
     "fileUrl": "..."
   }

If neither is explicitly supplied, the API resolves the tenant automatically from the API key credentials.

Tenant Isolation Guarantees

• Data Segregation: Work jobs, audit logs, and extraction results are partitioned strictly by tenant.
• Dedicated Queue Quotas: Cloud Tasks queue capacity and rate limits are metered per tenant so one partner's deadline rush never starves another.
• Custom Policy Catalogs: Handbooks, purchasing rules, and category catalogs are loaded according to the tenant and requested programKey.

---

Environments & Key Format

Environment	Key Prefix	Base URL
Sandbox / Staging	hp_test_...	https://staging-api.heypeppy.com/v1
Production	hp_live_...	https://api.heypeppy.com/v1

• Sandbox Environment: Connects to the same AI extraction models with test guidelines. No billable usage is charged, and test jobs are purged after 24 hours.
• Production Environment: High-availability multi-region deployment backed by Google Cloud Tasks and enterprise LLM quotas.

---

API Key Security Best Practices

1. Keep Keys Secret: Never expose API keys in client-side code (browsers, mobile apps) or commit them to public Git repositories.
2. Key Rotation: HeyPeppy supports simultaneous active keys to enable zero-downtime key rotation. You can generate a new secondary key in your partner portal before revoking the old key.
3. IP Allowlisting (Optional): Enterprise partners may specify static IP ranges (CIDR blocks) from which requests are accepted. Requests originating from outside allowed IPs will be rejected with HTTP 403 Forbidden.

---

Webhook Authentication

When HeyPeppy delivers asynchronous event notifications to your webhook URL, every request includes an HMAC-SHA256 signature in the X-HeyPeppy-Signature header.

Refer to the Webhooks Documentation for full instructions on verifying webhook signatures.