API Key

API Token · Access Key · Bearer Token

Definition

An API key is a secret identifier that authenticates requests to an API; it belongs on the server and must not appear in public frontend code.

How API key authentication works

The service issues a string — a random sequence, usually 32 to 64 bytes in base64 or hex. On every
request the client passes it in an HTTP header:

GET /api/recommendations?user_id=123
Authorization: Bearer sk-live-abc123def456...

X-API-Key: sk-live-abc123def456...

The server verifies the key, determines whose it is and what rights it carries, and responds
accordingly.

Access levels in an e-commerce integration

A correct architecture issues several keys with different rights:

Key type	Where it is used	Rights
Public (frontend)	JavaScript on the site	Read only: fetching recommendations, widgets
Private (backend)	Server, CI/CD	Writing events, managing configuration
Server write-only	An event collector	Writing events with no read access

A public key may sit in client code — but only when it is strictly read-only and bound to allowed
origin domains.

Common mistakes

A private key committed to a repository — automated scanners find it within minutes of publication
One key for every service — compromising it opens everything
Keys never rotated for years — after a leak there is no way to know when the exposure started
Keys in URL parameters — they end up in server logs, proxies and browser history

Frequently asked questions

How does an API key differ from an OAuth token?

An API key is a simple static string, often with no expiry. An OAuth token results from an authorisation flow, is bound to a specific user and expires. API keys are used for server-to-server integrations; OAuth is used where an application acts on a person's behalf.

Why must a private key never appear in client-side JavaScript?

Client code is visible to everyone. Anyone can open developer tools, find the key and use it for unauthorised requests: writing fake events, extracting data or exhausting rate limits. Public read-only keys are acceptable in the frontend only when they are strictly scoped and bound to allowed origins.

How should API keys be stored?

In environment variables — a server-side env file, secrets in the CI/CD system. Never in the source repository, never in git history, never in client-side JavaScript. Rotate them regularly and immediately on any suspicion of compromise.

Gravity Field

API Keys in a Gravity Field Integration

Gravity Field uses two levels of key: public (frontend, read-only recommendations) and private (backend, event writes and configuration). The private key must never reach client code.

✦Separated rights: a public key for widgets, a private one for the Event API

✦Key binding to the origin domain for additional protection

✦Key rotation from the control panel with no downtime

Explore the platform →