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	Upsert items and users (plus everything a publishable key can do)

The server enforces key type. Using the wrong key type for an endpoint returns 403 Forbidden.

If your secret leaks, rotate immediately

We cannot recover a leaked secret. Generate a new pair and revoke the old one rather than attempting to confirm what was accessed.

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. It is shown 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 /v1/ingest/events/ingest`	Publishable (`lehnz_pk_*`)
`POST /v1/ingest/items/upsert`	Secret (`lehnz_sk_*`)
`POST /v1/ingest/users/upsert`	Secret (`lehnz_sk_*`)
`POST /v1/ingest/upload/items`	Developer JWT (dashboard only)
`POST /v1/ingest/upload/users`	Developer JWT (dashboard only)
`POST /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 is otherwise suspected exposed. Plan a routine rotation at least once a year.

From Developer Access, click Generate Key Pair. A new pair is created without revoking the old one, giving you a brief overlap window to deploy.
Update your secret manager and redeploy with the new keys.
Once confirmed live, revoke the old pair. Requests with the old keys will return 401 Unauthorized.

Only OWNER and ADMIN members can generate or revoke keys; every generation, view, and revocation is recorded in the org's audit log.

Auth failures follow the standard envelope. See Errors & troubleshooting.