Authentication

Developer Guide
API Keys

ShipRateAPI uses API key authentication. Every request to the API must include your key in the x-api-key HTTP header. There is no OAuth flow or token exchange — the key is passed directly on each request.

POST /api/v1/quotes
Content-Type: application/json
x-api-key: sk_3f9a2c...

Keys are a sk_ prefix followed by 64 hex characters. There are no separate live and test key formats — a key is simply scoped to whichever store issued it.

Keep your key secret. Never expose it in client-side JavaScript, public repositories, or frontend code. All ShipRateAPI plugin integrations call the API server-side so the key never reaches the browser.

Generating a key
  • 1
    Log in to the ShipRateAPI admin portal
  • 2
    Navigate to Stores
  • 3
    Create a store. Its API key is issued automatically on creation — there is no separate “generate key” step
  • 4
    Copy the key immediately — it is only shown in full once. Only a hash is stored, so a lost key cannot be recovered, only rotated
Key scoping

Each store has exactly one API key, and that key is tied to that store. A key for Store A cannot be used to fetch rates for Store B. This means:

  • If you run multiple storefronts, create a separate store for each — one key per store is the unit of separation
  • Rate rules, carriers, and zones are all resolved in the context of the key's store
  • Rotating a key issues a new one and invalidates the old immediately — use Rotate key on the store for offboarding or security incidents. Because a store holds a single key, rotation is a hard cutover: update every integration using it at the same time
  • To stop a store serving rates without changing its key, suspend the store instead — suspended and not-yet-activated stores are rejected with a 403
Error responses
HTTP statusCause
401 UnauthorizedMissing or invalid x-api-key header
403 ForbiddenKey is valid, but the store is suspended or still pending activation
429 Too Many RequestsRate limit exceeded — 100 requests per 60 seconds, per IP. This is a burst limit, not a monthly quota: your plan governs how many stores you may create, not how many requests you may send. Back off and retry