Authentication & API keys

Every ingestion request authenticates with an operator API key sent in the x-api-key header:

x-api-key: plq_3f9a…c2b1

Keys are opaque, prefixed plq_, and shown once at creation — only a SHA-256 hash is stored, so a lost key can be revoked and replaced but never recovered.

Brand-pinned keys (recommended)

A key can be pinned to a single brand. This is the recommended shape for a PAM integration because the credential itself becomes the data-isolation boundary:

• Every event the key carries is attributed to its brand — always.
• Any x-brand header or ?brand= hint on the request is ignored. A pinned key can never write to a different brand, even by mistake or if leaked.

You issue a brand-pinned key from the dashboard:

Settings → Integrations → New API key → pick the Brand and an Access level, then copy the key.

For a PAM, choose the Ingestion only access level (see Scopes below).

Legacy tenant-wide keys

A key created without a brand is tenant-wide (legacy behaviour): it may write to any brand of the tenant, selecting the brand per request with the x-brand header or ?brand= query parameter (a brand id or slug). New integrations should prefer brand-pinned keys.

Scopes (least-privilege)

A key carries a set of scopes. An empty scope set means full access (legacy keys); a non-empty set restricts the key to those scopes.

A PAM ingestion key needs only events:write. If it is used against any other endpoint, the API responds 403 FORBIDDEN.

Rotating a key

Keys can be revoked at any time from Settings → Integrations. Revocation is immediate. Because only the hash is stored, rotation is always revoke + issue new — there is no “reveal” of an existing key.

Rotate a key if it ever appears in logs, screenshots, source control, or chat.

Who can manage keys

API-key management is a platform-owner (super_admin) concern (Tier 2). A tenant admin does not manage keys by default. The same permission gates the mapping engine configuration.

Errors