Skip to content

Get started

Authentication

Send your key in the Authorization header on every request:

Text
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.

ScopeLets the key
catalog:readRead your products, your competitors and your SKU links
matches:readRead comparison sets: competitor matches and prices
skus:writeCreate, 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:

codedetailCause
unauthenticatedSend Authorization: Bearer <API key>.No Authorization: Bearer header
invalid_keyThe API key is malformed.Wrong format or checksum: a typo or copy-paste damage
invalid_keyThe 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:

  1. Open your integration's credential setting, ready to paste.
  2. Select Regenerate in Settings → API & Integrations and confirm. The new key is shown once.
  3. Paste it into your integration and restart or reload what needs it.
  4. Call GET /v1/me from the integration. A 200 with the new prefix means you're done.