Authentication

Every request to the Peleka API needs an API key attached as a header. There's no OAuth flow, no session cookies, no signed request bodies: just a key and a header.

Creating a key

API keys are created from the dashboard, not the API itself. Go to Settings → API Keys in your workspace and click Create key. You'll be asked to name it (so you can tell it apart from other keys later, e.g. "CI pipeline" or "Zapier integration") and choose a scope.

The key is shown once, at creation time. Copy it somewhere safe: Peleka doesn't store the plaintext and can't show it to you again. If you lose it, revoke it and create a new one.

Scopes

Keys are read or write:

• read can call any GET endpoint: list contacts, fetch analytics, pull webhook delivery history.
• write can do everything read can, plus create, update, and delete: adding contacts, sending broadcasts, registering webhooks.

There's no per-resource scoping yet. A write key can touch every resource this API exposes, not just one, so if you're integrating with a third-party tool that only needs to read data, use a read key for it.

Sending the key

Attach it as the X-API-Key header on every request:

curl https://api.peleka.io/api/v1/contacts \
  -H "X-API-Key: pel_live_51H8x2KJ9mN..."

Keys are prefixed pel_ so they're easy to spot in logs, config files, or an accidental commit; grep for pel_ in your repo history if you're ever worried one leaked.

Requests without a valid key, or with a read key attempting a write, get a 401 or 403 with an RFC 7807 body explaining which:

{
  "type": "https://peleka.io/errors/403",
  "title": "Forbidden",
  "status": 403,
  "detail": "This API key has read-only access",
  "instance": "/api/v1/contacts"
}

Keeping keys safe

Treat an API key like a password. Don't commit it to source control, don't embed it in client-side JavaScript, don't paste it into a public Slack channel. If a key ships to production in a mobile app or browser bundle, anyone who decompiles or inspects the bundle has it.

If you suspect a key has leaked, revoke it immediately from Settings → API Keys and issue a new one — revoking takes effect instantly, and any request using the old key starts failing right away.