The API uses OAuth 2 client credentials: an API key is exchanged for a short-lived access token, and the token goes on every request.
API keys
A key has two parts:
| Part | Looks like | Where it goes |
|---|---|---|
| Access Key ID | pgod_test_ak_… or pgod_live_ak_… |
Safe to log; identifies the key |
| Secret Key | pgod_test_sk_… or pgod_live_sk_… |
Secret. Shown once, when the key is created or rolled |
test keys work in test mode only; live keys place real orders (see Test mode and going live).
You create test keys yourself on On Demand → Developers. Live keys are issued by our team when your test orders work. Each key has its own scopes:
| Scope | Allows |
|---|---|
catalog:read |
GET /catalog/…, POST /quotes, GET /quotes/{id} |
orders:read |
GET /orders, GET /orders/{id}, /by-external-id, /shipments, /invoice |
orders:write |
POST /orders, POST /orders/{id}/cancel |
webhooks:manage |
/webhook-endpoints and /events |
Give each key only the scopes it needs. You can have up to 10 active keys.
Get an access token
POST /api/on-demand/v1/oauth/token
Authorization: Basic base64(AccessKeyID:SecretKey)
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
Optional: scope=catalog:read orders:read asks for fewer scopes than the key has.
{ "access_token": "pgod_at_…", "token_type": "Bearer", "expires_in": 3600, "scope": "catalog:read orders:read" }
Rules:
- Send the Secret Key with HTTP Basic only. A Secret Key in the request body is refused, and you should roll that key.
- A token lasts 3600 seconds (60 minutes). Cache it and reuse it; you can request at most 20 tokens a minute per key.
- Never put a key or token in a URL. A request with credentials in the query string is refused with
credentials_in_url.
Use the token
GET /api/on-demand/v1/account
Authorization: Bearer pgod_at_…
GET /account is a good first call: it shows your partner account, whether the key is live, your billing method, your order limits and the key's scopes.
When a token expires you get 401 token_expired: request a new token and retry.
Roll or revoke a key
On On Demand → Developers:
- Roll issues a new Secret Key for a test key. The old Secret Key, and every token made with it, stops working at once.
- Revoke switches a key off for good, with all its tokens.
If a live Secret Key may have leaked, revoke it straight away and contact us for a new one.
IP allowlist
On request, we can limit a key to your servers' IP addresses. Calls from any other address get 403 ip_not_allowed.
Keeping keys safe
- Keep Secret Keys on your server only: never in a browser, a mobile app or a public repository.
- Use a different key per system (your store, your warehouse app…), so you can roll one without stopping the others.
- Watch Recent API requests on the Developers tab for calls you do not recognise.
