Skip to main content

API Key Authentication

Every site you add to StorePilot receives a unique API key — the site's SECRET key. Three things hold it, and all three are servers:

  • the WordPress plugin, which proxies its collectors' reports;
  • the Node SDK, which reports your own backend's exceptions;
  • your build pipeline, when it uploads source maps.

A browser never holds it. A site installed with the loader tag alone authenticates with a separate public key, which only NAMES the site — the request is authorised by its Origin, which a page script cannot forge.

Where to Find Your API Key​

  1. Log in to the Platform dashboard
  2. Open your site
  3. Go to Settings → Installation
  4. The API key is shown there, labelled API key — only an admin or the owner can see it

The key is a UUID-style string, for example:

5f3a2b1c-8e4d-4f9a-b7c6-1a2b3c4d5e6f

How the Key Is Used​

The WordPress plugin sends the API key in the X-StorePilot-Key request header on every ingest call:

POST /ingest/errors HTTP/1.1
Host: api.store-pilot.net
X-StorePilot-Key: 5f3a2b1c-8e4d-4f9a-b7c6-1a2b3c4d5e6f
Content-Type: application/json

{ "message": "...", "source": "...", ... }

The Platform validates the key on every request and resolves the associated siteId. If the key is missing or invalid, the request is rejected with 401 Unauthorized.

Protecting Your API Key​

Keep the API key on your servers. It is not the credential a browser uses: the loader tag carries the site's separate public key, and the platform decides whether to believe that one by checking the request's Origin against the site's registered domains.

Ingest endpoints are write-only either way — they accept event data and cannot be used to read anything back out of the platform — but the secret key authenticates without an Origin check, which is why it belongs in an environment variable and not in page source.

To further limit risk:

  • The Platform only accepts ingest requests from the origin domain registered for the site
  • Rotating the key immediately revokes the old one

Rotating the API Key​

Rotation is the site owner's to do, and the dashboard has no button for it: call POST /api/v1/sites/{siteId}/api-key/rotate signed in as the owner, or ask support. The response carries the new key, and Settings → Installation shows it from then on. The previous key stops working at once — it is replaced, not disabled — so put the new one into the StorePilot screen in WordPress Admin (and anywhere else it is used, such as the Node SDK or a source-map upload step) straight away.

caution

Rotating the key will cause all ingest requests to fail until the new key is entered in the Plugin Settings.

Dashboard Authentication (JWT)​

The Platform dashboard uses a separate JWT-based authentication (not the API key). Dashboard users log in with email/password and receive:

  • An access token (short-lived, 15 minutes) stored in memory
  • A refresh token (7 days) stored in an HttpOnly cookie

This separation ensures that even if an API key is leaked, an attacker cannot log in to the dashboard.