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.

Sending the key without a custom header

Some senders (e.g. a PAM/tracking system that only fires a POST at a fixed URL) cannot set a custom header. The same key is therefore also accepted as:

Authorization: Bearer plq_3f9a…c2b1          # standard bearer header
POST /api/v1/events?api_key=plq_3f9a…c2b1     # query parameter

All three sources resolve to the same key (header is tried first, then bearer, then query). Over HTTPS the query string travels inside the TLS tunnel, and the key is still hashed, brand-pinned, scoped and revocable — but a URL-embedded key can land in access logs, so prefer the x-api-key header whenever the sender supports one.

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