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://app.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 v1 endpoint published today |
pim:write | Edit draft values | Future v1 write endpoints (additive) |
pim:publish | Publish to Shopify | Future v1 publish endpoints (additive) |
pim:webhooks | Manage webhooks | Future v1 webhook endpoints (additive) |
Principle of least privilege.
Since every published endpoint is a read, a pim:read-only key is all any integration needs today. Mint wider keys only when the endpoints that use them ship.
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/v1paths, and only an API key can reach them — a browser session or Shopify session token is refused there with403. 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.