Get started
Authentication
Send your key in the Authorization header on every request:
Authorization: Bearer gp_live_…There is no other way to send it. The API never accepts a key in a URL, because URLs end up in logs.
Scopes#
Each key has scopes that limit what it can do. GET /v1/me lists them.
| Scope | Lets the key |
|---|---|
catalog:read | Read your products, your competitors and your SKU links |
matches:read | Read comparison sets: competitor matches and prices |
skus:write | Create, replace and remove SKU links |
A key without the scope an endpoint needs gets 403 insufficient_scope. A key created in Settings has all
three scopes.
Keep your key safe#
- Treat the key like a password. Anyone who has it can read your competitor prices.
- Store it in an environment variable or a secrets manager. Never put it in source code or a Git repository.
- Call the API only from servers. Browsers can't call it (no CORS headers), so a key can't work from a web page.
- Your organisation has one key. Give it only to the systems that need it, and regenerate it if anyone else has seen it.
Keys start with gp_live_ so secret scanners can spot a leaked one. They end with a checksum, so a mistyped key
fails at once with 401 invalid_key. A PUT without a valid key fails with 401 before GetPrice reads its body.
On write endpoints only three body checks run before the scope check: a body over 1 MB (413), a body that
isn't application/json (415) and a body that isn't valid JSON (422). A read-only key that sends a non-JSON
body therefore gets 415 before 403 insufficient_scope, while a well-formed body with a missing field gets
403 before 422.
A 401 tells you which check failed:
code | detail | Cause |
|---|---|---|
unauthenticated | Send Authorization: Bearer <API key>. | No Authorization: Bearer header |
invalid_key | The API key is malformed. | Wrong format or checksum: a typo or copy-paste damage |
invalid_key | The API key is not valid. | Unknown, revoked or expired, or the account is closed. The API doesn't say which |
Branch on code. detail is for people, and its wording may change.
Warning: If a key leaks, an admin regenerates it at once in Settings → API & Integrations → Regenerate. The old key stops working within about a minute.
Regenerating replaces the key immediately: there is no overlap, and anything still using the old key gets
401 invalid_key within a minute. Revoke on the same page removes the key without creating a new one.
Rotate your key#
To keep the gap short:
- Open your integration's credential setting, ready to paste.
- Select Regenerate in Settings → API & Integrations and confirm. The new key is shown once.
- Paste it into your integration and restart or reload what needs it.
- Call
GET /v1/mefrom the integration. A200with the new prefix means you're done.