Authentication

Every request to the Pinch API is authenticated with an API key sent in the Authorization header. Keys are issued per merchant and per environment.

Get an API key

API keys are managed by the Pinch team during onboarding. To request a key, email support@pinch.ai with:

• Your company name and Pinch account email
• The environment(s) you need (sandbox, production, or both)
• Whether the key is for your own integration or a partner / RMS

For most merchants, Pinch provisions two keys during onboarding: one for sandbox and one for production. Treat them like passwords.

Send the key in the Authorization header

Set the Authorization header on every request. Pinch does not use a Bearer prefix — paste the key value directly:

Authorization: pk_live_a1b2c3d4e5f6...

Full request:

curl

curl https://api.pinch.ai/v1/order \
  -H "Authorization: $PINCH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ ... }'

Node

const response = await fetch("https://api.pinch.ai/v1/order", {
  method: "POST",
  headers: {
    "Authorization": process.env.PINCH_API_KEY,
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify(payload)
});

Python

import os, requests

response = requests.post(
    "https://api.pinch.ai/v1/order",
    headers={
        "Authorization": os.environ["PINCH_API_KEY"],
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json=payload,
)

Key format

Keys are opaque strings, typically 40+ characters. The prefix tells you which environment a key belongs to:

Prefix	Environment
pk_test_	Sandbox — read/write to qa.pinch.ai and qa-api.pinch.ai
pk_live_	Production — read/write to api.pinch.ai

Using a sandbox key against the production base URL (or vice versa) returns 401 unauthenticated.

Storing keys

API keys grant full access to your Pinch account. Store them like any other production secret:

• Never commit keys to source control. Use a secrets manager (AWS Secrets Manager, GCP Secret Manager, Vault, Doppler, 1Password CLI) or .env files that are .gitignored.
• Server-side only. Never expose a key in client-side JavaScript, mobile apps, or shipped binaries.
• Rotate annually at minimum, and immediately on team turnover or suspected leak.

Rotating a key

To rotate without downtime:

1. 1
   Request a new key

   Email support@pinch.ai. Pinch can have two active keys per environment at the same time during a rotation window.

2. 2
   Deploy the new key to your services

   Update your secrets manager. Confirm every service that talks to Pinch is now using the new key (check logs).

3. 3
   Notify Pinch to revoke the old key

   Once you've confirmed all traffic is on the new key, reply to the rotation thread. Pinch revokes the old key on a confirmed timestamp.

Scoped keys for partners

If you're integrating Pinch on behalf of another merchant (RMS, agency, platform), request a scoped partner key. Partner keys are restricted to a specific merchant account and can be revoked without affecting your own production traffic.

Errors

Authentication failures all return HTTP 401:

Error code	Cause	Fix
unauthenticated	Authorization header missing	Add the header to your request
invalid_api_key	Key format invalid or revoked	Verify the value and prefix; rotate if revoked
environment_mismatch	pk_test_ key against api.pinch.ai (or vice versa)	Switch the base URL or the key

See Errors for the full error model.

See also

• Environments — sandbox vs production URLs
• Errors — error envelope format and codes
• REST API Quickstart — your first authenticated request