Skip to content

Authentication, keys and scopes

How API keys work, how to send them, what each scope allows, and how keys are created, expired and revoked.


API Keys

One key, one workspace

Every request is authenticated with an API key. A key is a 49-character token beginning pmk_live_, bound to the workspace it was created in, carrying the scopes chosen at creation. Pricemaster stores only a hash of it: the clear text is shown once, when it is created, and cannot be retrieved later.

Send it in the Authorization header on every request:

Authorization: Bearer pmk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
Nothing else is accepted. The API host reads no cookies and no query-string tokens, so a browser session can never reach it by accident and there is no cross-site request risk. Keys for the mobile app are a different kind of token and do not work here.

Confirm a key with GET /v1/me: it answers with the workspace the key unlocks and the scopes it carries, whatever scopes it has.

curl https://api.pricemaster.ai/v1/me -H "Authorization: Bearer $PRICEMASTER_KEY"
Scopes

Give a key only what its job needs

Each endpoint names the scope it requires. A key without that scope receives 403 insufficient_scope, and the response names the missing scope. workspace:read is always included.

ScopeAllowsKind
workspace:readRead the workspace: name, type, currency, tax rate, modules, trial state and the key's own details (/v1/me).read
products:readRead your products: SKU, title, identifiers, cost, prices, stock, tags and market position.read
products:writeUpdate product facts: cost, stock, RRP, MAP, enabled and monitor-only. Never sends a price to your store.write
market:readRead competitor offers, competitor price history, the sellers tracked for the workspace and price recommendations.read
market:writeSwitch a competitor on or off for the workspace, exclude or prefer a listing on a product, request a fresh read of a competitor page.write
rules:readRead pricing rules, their settings and which rule prices each product.read
rules:writeCreate, edit, enable, disable, reorder and delete pricing rules; assign and unassign products. Never sends a price.write
tags:readRead the workspace's tags.read
tags:writeCreate, rename, delete manual tags and change which products carry them.write
margins:readRead the minimum-margin default, cost bands and product-group tables.read
margins:writeChange the minimum-margin default, add, edit and delete cost bands and product-group tables.write
pushes:readRead store push operations and their per-product results.read
pushes:writeSend prices to your store by hand (a rule's prices for chosen products, one exact price, or the whole workspace's rules) and roll a push back. Never switches automatic pushing on.write

Write scopes can only be chosen once Pricemaster has enabled API writes for the workspace, and pushes:write only once API price pushes is enabled as well. Until then those options are greyed out in Settings, and a key created earlier cannot be widened: create a new key and revoke the old one.

Lifecycle

Creating, expiring and revoking keys

1

Create

In Settings → API access: a name (the system that will use it), the scopes, and an optional expiry of 30, 90 or 365 days. Up to 10 live keys per workspace.

2

Identify

Lists in the app, HQ and support show only the key's prefix (pmk_live_a1b2c3d4…). Quote the prefix, never the key, when you contact us.

3

Rotate

Create the replacement, deploy it, then revoke the old key. Both work during the overlap.

4

Revoke

Instant: the next request with the key gets 401 key_revoked. Any member of the workspace can revoke a key, and so can Pricemaster.

An expired key answers 401 key_expired. The Last used column in Settings shows when and from which address each key was last seen, so an unexpected caller stands out.

IP Allow-Lists

Pin a key to your servers

A key can carry a list of IP addresses or CIDR ranges; requests from anywhere else get 403 ip_not_allowed. Allow-lists are set by Pricemaster on request for now (email the key prefix and the ranges); self-service follows.

Security Practices

Keep the key a secret

  • Store keys in your secret manager or environment, never in source control, client-side code or spreadsheets.
  • One key per system. When a system is retired, revoke its key.
  • Prefer read-only keys. Ask for writes only for the integration that needs them.
  • Set an expiry for anything experimental.
  • If a key may have leaked, revoke it first and create a new one second. Revocation is immediate.

Every API write and every key event is recorded in the workspace's audit log with the key's prefix and the request id.