Skip to main content

Authentication

Prove who you are on every request by sending one header — your API key — and get back only your own account's data.

Paylode's API uses a single API key to authenticate you. The key identifies your client account and scopes every response to your data: you never have to pass a client id to "filter" results, because the key already fences them. Most APIs read the key from a header; a few URL-embedded flows accept it as a query parameter instead. There are no OAuth flows, no token exchange, and no refresh step for the core API — one key, on every call.

One exception: the analytics API doesn't use your API key directly. You trade your key for a short-lived analytics token first. That flow lives in Analytics → Authenticate; everything on this page is about the core API.

Get your key​

Your API key is provisioned with your account and shown in the admin app, under the integration area on the API tab. Keep the key server-side — treat it like a password, never commit it, and never ship it in client-side code you don't control.

The X-API-Key header​

Send your key in the X-API-Key header on every authenticated request. Here's the smallest useful call: list the perk collections your account can see. It needs nothing but your key, so it's the ideal first request to confirm auth works.

curl https://perk-collections.paylode.com/perk-collections \
  -H "X-API-Key: sk_example_0000000000000000000000000000"
const res = await fetch(
  "https://perk-collections.paylode.com/perk-collections",
  { headers: { "X-API-Key": "sk_example_0000000000000000000000000000" } }
);
const collections = await res.json();

The response is a list of collection identifiers your key can access — a string per collection:

["example-rewards", "example-partner-deals"]

Because the key scopes the response, this list contains your collections and no one else's. From here you'd fetch a specific collection to render it — see Embed a perks page or Build a custom perk page.

The api_key query parameter​

Some APIs — notably Boost and the perk-collections read APIs — also accept the key as an api_key query parameter. This exists for flows where the request is a URL you can't attach headers to (an iframe src, a link you hand to a browser). Prefer the header everywhere you control the request; reach for the query form only when you can't set a header.

curl "https://perk-collections.paylode.com/perk-collections?api_key=sk_example_0000000000000000000000000000"
caution

Query keys end up in logs. A key in a URL is visible in browser history, proxy logs, and server access logs. Only use api_key where a header is genuinely impossible, and never for a call you make from your own backend.

Roles​

Keys carry a role — USER or ADMIN. For most client integrations this distinction is invisible: your key does what your account is entitled to do. A handful of endpoints are ADMIN-only and will return 403 for a USER key; the developer reference marks those per operation. If a call you expect to succeed returns 403, check whether it's an admin-scoped operation.

Errors​

StatusMeaningWhat to do
401Key missing, malformed, or not recognizedConfirm the X-API-Key header is present and copied exactly, with no surrounding whitespace.
403Authenticated, but not allowedThe operation needs a role or entitlement your key doesn't have.

Key matching is case-insensitive, so casing won't cause a 401 — a 401 means the key isn't reaching us intact or isn't recognized at all.

Reference​

The platform authentication scheme and the security requirements on each operation are documented on the developer site — developers.paylode.com. Each operation lists whether it accepts the header, the query parameter, or both.