#Authentication

Every request carries an API key as a bearer token:

Authorization: Bearer <api key>

#Creating a key

You need the owner role on the company, and the company must be on a paid plan.

1. Sign in at https://app.getponch.com and switch to the company the key is for.
2. Go to Integrations → API keys (https://app.getponch.com/dashboard/integrations/api-keys/).
3. Enter a Label that says where the key will be used, e.g. Zapier or POS terminal, and click Create key.
4. Copy the key from the box that appears. This is the only time the full key is shown. Ponch stores only a hash, so a lost key can't be recovered: revoke it and create a new one.

The key list then shows each key's label, its first eight characters (the prefix, for telling keys apart), when it was created, when it was last used, and whether it is active.

If your plan doesn't include API access, or the account has more active cards than its plan allows, the page shows an upgrade prompt instead of the form. Keys you already have keep working while you're over the card limit.

#One key, one company

A key is tied to the company that was active when you created it. It can read and change that company's stores, templates, cards and customers, and nothing else. If you run several brands as separate companies, create one key per company and one connection per key.

A key has company-level access. It isn't bound to a store, and stamping with a key isn't limited by the per-store stamping rule that applies to staff.

#Revoking and deleting

Both actions are on the API keys page.

• Revoke stops the key from working immediately. The key stays in the list, marked Revoked.
• Delete removes it from the list permanently.

Anything using the key starts getting 401 on its next request.

#When a key is rejected

A rejected key gets:

HTTP/1.1 401 Unauthorized

{"detail": "Unauthorized"}

This happens when:

• the header is missing or malformed, or the key is mistyped (watch for a trailing newline from copy-paste)
• the key was revoked or deleted
• the company or account was deactivated
• the account moved to a plan without API access, e.g. after a lapsed payment

The response is the same in every case. A client should treat any 401 as "reconnect your Ponch account", not as an outage, and should not retry it.

Some endpoints you'll see in the playground are for the Ponch dashboard only, and an API key gets 401 from them too. The endpoint reference lists every endpoint an API key can call.

#Keeping keys safe

• Treat a key like a password. It can add stamps and redeem rewards.
• Use one key per integration, so you can revoke one without breaking the others.
• Never put a key in a web page, a mobile app or anything else that ships to customers.