Authentication

API keys

Every request to the lehnz API is authenticated with an API key. Each organization gets one key pair: a publishable key for client-side code and a secret key for your servers.

The two key types

Type	Prefix	Where it's safe	What it can do
Publishable	`lehnz_pk_…`	Browser, mobile apps, client-side code	Send events, fetch recommendations
Secret	`lehnz_sk_…`	Server-side only — never ship to a browser	All publishable scopes, plus any future write-heavy endpoints

The server enforces key type. Sending a secret key from a public endpoint (or vice versa) returns 403 Forbidden.

If your secret leaks, rotate — don't verify

We cannot recover a leaked secret. After any suspected exposure, generate a new pair and revoke the old one rather than attempting to confirm what was leaked.

Generating your first pair

Sign in to the dashboard.
Open Developer Access.
Click Generate Key Pair. The dashboard shows both keys.
Copy the secret key immediately into your secret manager. The dashboard shows it exactly once. After this dialog closes, only the publishable key remains visible.

Lost secret = revoke and reissue

If you lose the secret, you cannot retrieve it. Revoke the existing pair and generate a new one.

Sending the key

Pass the key in the X-API-KEY header on every request. There is no Bearer prefix.

request-header.txt

X-API-KEY: lehnz_pk_…

Which key for which endpoint

Endpoint	Accepted auth
`POST /api/v1/events/ingest`	Publishable (`lehnz_pk_*`)
`POST /api/v1/items/upsert`	Secret (`lehnz_sk_*`)
`POST /api/v1/users/upsert`	Secret (`lehnz_sk_*`)
`POST /api/v1/upload/items`	Developer JWT (dashboard only)
`POST /api/v1/upload/users`	Developer JWT (dashboard only)
`POST /api/v1/recommend`	Publishable (`lehnz_pk_*`)

Bulk file imports happen from the dashboard rather than the public API — see Load your catalog.

Rotating keys

Rotate immediately if a key is committed to a public repo, leaks via a log, or any other suspected exposure. Plan a rotation at least once a year for healthy hygiene.

From Developer Access, click Generate Key Pair. This creates a new pair without revoking the old one — you have a brief overlap window to deploy.
Update your secret manager and redeploy your services with the new keys.
Once you've confirmed the new keys are live, revoke the old pair from the dashboard. Subsequent requests with the old keys will return 401 Unauthorized.

Only members with OWNER or ADMIN role can generate or revoke keys.

Permissions

Role	View keys	Generate / revoke
OWNER	Yes	Yes
ADMIN	Yes	Yes
DEVELOPER	Yes (masked)	No
MEMBER	No	No

Every generation, view, and revocation is recorded in the org's audit log.

Errors

Status	Cause	Fix
`401`	Missing or malformed `X-API-KEY` header	Confirm the header is set and starts with `lehnz_pk_` or `lehnz_sk_`.
`401`	Key was revoked or never existed	Check the dashboard. If the key shows as revoked, generate a new pair.
`403`	Wrong key type — e.g. publishable on a secret-only endpoint	Check the table above.
`403`	Caller's role lacks permission to manage keys	Ask an OWNER or ADMIN to perform the action.
`429`	Too many requests across this org's keys	Back off. See Retries & rate limits.