API keys

API keys authenticate calls from your code to the platform's APIs. Keys live inside Applications, not as a separate top-level surface — to manage keys, you manage Applications under Connect.

This page is about the lifecycle and security practices; for the page that actually shows the keys, see Connect.

Two kinds of keys per Application

Each Application has two keys:

Key	Where it goes	Use for
API Key (secret)	Server-side only. Environment variable, secret manager.	Authenticated server-side calls.
Public Key	Safe in browsers, mobile apps, anywhere clients see code. Prefixed pk_development_… or pk_live_….	Client-side SDKs, hosted-checkout init.

The secret is a long signed token (a JWT in the dev environment). Treat it as a password — anyone with it can act as your Application against the platform.

Confirm the prefix scheme

Observed pk_development_… on the dev environment. Confirm the production prefix (likely pk_live_…) and document.

Get a key

Go to Connect → Applications and click + Add new App. Once the App is saved, its detail page shows both keys with Copy buttons.

Use the key

Pass the secret in the Authorization header on every server-side request:

curl https://api.<your-host>.com/v1/transactions \
  -H "Authorization: Bearer $POMELO_API_KEY"

Confirm base URL + auth header format

Replace the snippet with the real production base URL and confirm Bearer is the right scheme (vs. X-API-Key, basic auth, etc.).

In code, never hard-code the key — load it from an environment variable:

Node / TypeScript

const apiKey = process.env.POMELO_API_KEY;
if (!apiKey) throw new Error('POMELO_API_KEY is not set');

const res = await fetch('https://api.<your-host>.com/v1/transactions', {
  headers: { Authorization: `Bearer ${apiKey}` },
});

Rotate a key

There's no observed in-place "rotate" affordance on the Application detail. Rotation is via delete + recreate:

1. Create a new Application (the new key is shown immediately).
2. Roll the new key out to your services.
3. Verify nothing is still using the old key.
4. Delete the old Application.

This means a brief overlap where both keys are valid — exactly what you want for zero-downtime rotation.

Confirm there's no in-place rotation

If the Application detail has a "Rotate key" affordance hidden in a menu I missed, document it here and skip the delete-and-recreate step.

Revoke a key

Click Delete App on the Application's detail page in Connect. All keys for that App stop working immediately.

Deletion is irreversible

You can't restore a deleted Application. If you delete the wrong one, create a new one and roll its keys out.

One Application per integration

Use a separate Application for each thing that calls the API:

• Production backend → its own App
• Staging backend → its own App
• Reconciliation script → its own App
• Mobile app (uses public key) → its own App

That way you can rotate or revoke each one independently.

Security practices

• Never commit keys to source control. Use a secret manager or environment variables.
• Never paste keys into shared docs, tickets, screenshots, or chat. Treat the value like a password.
• Use a different App per environment. Production and dev should never share keys.
• Rotate on a schedule — quarterly is a reasonable default — and immediately if there's any chance of leak.
• Use the Public Key for clients, the API Key for servers. If you find yourself wanting to call an authenticated endpoint from a browser, route the call through your own backend instead.

Related

• Connect — where Applications and their keys are managed.
• Authentication — full overview of auth schemes.
• Webhooks — separate signing keys, different lifecycle.