An API key tells PSRESTful which account is calling. Use a private key on your servers and send it in the x-api-key header. Use a public key only in code that runs in a browser: it works only from the websites you add to Allowed origins.
Private or public?
Private keys are for backend systems, like a nightly product import. Anyone who has one can call the API as your account, so it stays on your server. Your account also needs an active private key for the Data Explorer, the CSV Exporter, credential tests and the other dashboard tools.
Public keys are for code that runs in a visitor's browser, like showing live stock on a product page. Anyone who opens the page can see the key, so PSRESTful only accepts it from the origins on your Allowed origins list.
Each tab on the API Keys page lists its own keys. Keys belong to the account, not to the person who made them, and the Created By column shows who did.
Create a key
The API Keys page is in the user menu for Admin and Developer users.
- Open API Keys from your user menu, or go to /dashboard/api-keys/.
- Click the Private Keys or Public Keys tab.
- Click Generate API Key.
- Click the clipboard icon (Copy to clipboard) on the new key.
- Paste the key into your system's settings.
A public key also needs each website that will use it on your Allowed origins list:
- Open Settings from your user menu.
- Click the Allowed origins tab.
- Click Add Origin.
- Enter the site in Origin URL, like
https://example.com. - Click Add Origin to save it.
Send the key with each call
Send a private key in the x-api-key header:
curl -H "x-api-key: YOUR_PRIVATE_KEY" \
"https://api.psrestful.com/v1.1.0/suppliers/PCNA/medias/TM97813/?environment=PROD"
Send a public key as the pub_api_key query parameter, from a page on one of your allowed origins:
https://api.psrestful.com/v2.0.0/suppliers/HIT/inventory/5989?pub_api_key=YOUR_PUBLIC_KEY
Every call made with your keys counts toward your account's daily limit (see API limits and the 429 error). Endpoints and parameters are in the API docs.
Keep private keys secret
- Keep them in your server's configuration. Never put a private key in a web page, a mobile app or a public code repository.
- For sending purchase orders and other account operations, the API docs recommend OAuth2 tokens over a private key, because tokens are short-lived. See the OAuth2 guide.
- If a private key leaks, generate a new one and delete the old one right away.
Rotate a key
There's no rotate button: you make a new key, move your systems to it, then delete the old one. The Age (days) column shows how old each key is, and the page shows a warning once any key is older than 30 days.
- Click Generate API Key on the same tab as the old key.
- Put the new key into every system that uses the old one.
- Check that those systems still work.
- Click the trash icon (Delete API key) on the old key.
- Confirm the deletion.
The API reads the header as X-API-Key, and header names aren't case-sensitive. A call with no key gets 403 "Anonymous users don't have access to this endpoint", and an unknown or deleted key gets 403 "Invalid API key". The API caches each key for up to five minutes, so a deleted key can keep working for a few minutes after you delete it. Public keys are matched exactly against the request's Origin header (or Referer), so https://example.com and https://www.example.com are separate entries. Purchase order endpoints don't accept public keys.