Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.retailgrid.io/llms.txt

Use this file to discover all available pages before exploring further.

The Retailgrid Public API uses bearer tokens. Each request must include an Authorization header with your API key. 
Authorization: Bearer rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
API keys are prefixed rg_live_ and are scoped to a single Retailgrid account.

​
Generate an API key

  1. Sign in to app.retailgrid.io.
  2. Open Settings → Integrations.
  3. Find the API access card and click Generate API Key.
  4. Copy the key from the modal.
The key is shown only once, at the moment of creation. Retailgrid does not store the plaintext value, so it cannot be retrieved later. Save it to your secret manager immediately.
Each account can have one active key at a time. Generating a new key replaces the previous one - existing integrations using the old key will start receiving 401 Unauthorized and need to be updated.

​
Verify a key

The fastest way to check that a key works is to call GET /v1/auth/verify: 
curl https://clientapi.retailgrid.io/v1/auth/verify \
  -H "Authorization: Bearer $RETAILGRID_API_KEY"
A successful response confirms the key is valid and tells you which user and key id it belongs to: 
{
  "ok": true,
  "user_id": "f1c7e0b8-4a2b-4d0e-9a8b-2c3d4e5f6a7b",
  "api_key_id": "9f1c7e0b-4a2b-4d0e-9a8b-2c3d4e5f6a7b"
}
See the full reference on the Verify API key page.

​
Failure modes

StatusMeaning
401 UnauthorizedHeader missing, malformed, or the key is no longer active (rotated, revoked, or deleted).
403 ForbiddenKey is valid but does not have access to the requested resource.

​
Security guidance

  • Never commit keys to source control. Use environment variables, a secrets manager, or your CI’s encrypted variables.
  • Rotate on suspicion. Generating a new key in the UI immediately invalidates the previous one. There is no separate revoke step.
  • Use a dedicated key per integration where possible - because each account holds one active key today, plan key rotations to align with deploys of dependent services.
  • Treat keys like passwords. A leaked key gives full read/write access to your Retailgrid catalog and transactions.

​
Need help?

If a key stops working unexpectedly or you need a key reset for an account you no longer have UI access to, contact support.