Getting started

Authentication

Every request to the Public API carries an API key as a bearer token. Keys are created by a signed-in store user, belong to exactly one account, are scoped, and are revocable at any time.

Create an API key

Sign in to Peak PIM.
Open Settings → API.
Choose the key's access level (the scopes it carries) and create it.
Copy the key — it starts with pk_live_ and is shown once. Keys are stored hashed, so it cannot be displayed again later.

Use it

Send the key in the Authorization header of every request:

curl https://api.peak-pim.com/api/v1/ping \
  -H "Authorization: Bearer pk_live_..."

A 200 from /api/v1/ping proves the key end to end: it passed authentication, the route allowlist, its scope check, and the rate limiter.

Scopes

A key carries a fixed set of scopes chosen at creation. A request to a route the key's scopes don't cover fails with 403 forbidden_scope.

Scope	Grants	Used by
`pim:read`	Read the catalog	Every read endpoint — all the GETs in v1
`pim:write`	Edit draft values	Data-health scans and remediation batches (the first write endpoints, shipped 2026-07-31), plus future entity writes (additive)
`pim:publish`	Publish to Shopify	Future v1 publish endpoints (additive)
`pim:webhooks`	Manage webhooks	Future v1 webhook endpoints (additive)

One more scope exists in the contract but not on keys: POST /api/v1/data-health/unused-deletions requires pim:delete, which key creation cannot grant. That endpoint is documented but RESERVED — it answers 403 for every credential that exists today. See Data health.

Principle of least privilege.

A pim:read-only key still covers every read — most integrations need nothing more. But a read-only key is no longer enough for data-health automation: running scans or remediation batches takes pim:write. Add a scope only when your integration calls the endpoints that use it.

Security model

Account-bound. A key reads exactly one account's data. There is no account parameter anywhere in the API — tenancy is derived from the key, and another account's ids answer 404 not_found, indistinguishable from ids that don't exist.
Strict credential separation. An API key can only reach /api/v1 paths, and only an API key can reach them — a browser session or Shopify session token is refused there with 403. The internal application API is a separate, unversioned surface that changes freely; never program against it.
Keys cannot manage keys. Creating, listing, and revoking keys is only possible for a signed-in store user in Settings → API. A leaked key can never mint another key, extend itself, or hide its own revocation.
Hashed at rest, live lookup. Keys are stored hashed and validated on every request, so revoking one takes effect on its very next request.

Rotation and revocation

Revoke a single key, or all keys at once, in Settings → API.
To rotate: create the new key, deploy it, then revoke the old one. Both are valid during the overlap.
Treat keys like passwords: keep them in a secret manager, never in client-side code, repositories, or logs.