Authentication, keys and scopes
How API keys work, how to send them, what each scope allows, and how keys are created, expired and revoked.
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
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"
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.
| Scope | Allows | Kind |
|---|---|---|
workspace:read | Read the workspace: name, type, currency, tax rate, modules, trial state and the key's own details (/v1/me). | read |
products:read | Read your products: SKU, title, identifiers, cost, prices, stock, tags and market position. | read |
products:write | Update product facts: cost, stock, RRP, MAP, enabled and monitor-only. Never sends a price to your store. | write |
market:read | Read competitor offers, competitor price history, the sellers tracked for the workspace and price recommendations. | read |
market:write | Switch 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:read | Read pricing rules, their settings and which rule prices each product. | read |
rules:write | Create, edit, enable, disable, reorder and delete pricing rules; assign and unassign products. Never sends a price. | write |
tags:read | Read the workspace's tags. | read |
tags:write | Create, rename, delete manual tags and change which products carry them. | write |
margins:read | Read the minimum-margin default, cost bands and product-group tables. | read |
margins:write | Change the minimum-margin default, add, edit and delete cost bands and product-group tables. | write |
pushes:read | Read store push operations and their per-product results. | read |
pushes:write | Send 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.
Creating, expiring and revoking keys
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.
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.
Rotate
Create the replacement, deploy it, then revoke the old key. Both work during the overlap.
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.
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.
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.