Authentication

API keys & authentication

Every Lumen Sieve request must be authenticated with a Bearer token. Here's everything you need to know.

API key format

Lumen Sieve API keys follow a predictable format so you can identify them at a glance:

text

lumen_{env}_{type}_{random_hex}

Examples:
  lumen_test_sk_a3f9b2c1d4e5f6a7b8c9d0e1f2a3b4c5
  lumen_live_sk_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c

Segment	Values	Meaning
`env`	test · live	Test keys are safe for development; no billing impact
`type`	sk	Secret key — never expose in client-side code

Warning: Secret keys are shown exactly once on creation. Lumen Sieve does not store the raw key — only a one-way hash. If you lose it, revoke and generate a new one.

Sending the key

Pass the key as a Bearer token in the Authorization header on every request:

cURL

bash

curl https://api.lumen.com/v1/profiles/lookup \
  -H "Authorization: Bearer lumen_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"businessName":"Blispa Barbershop & Spa","countryHint":"KE"}'

Note: Never put secret keys in query parameters or request bodies. Headers are excluded from most server logs; query parameters are not.

Scopes

Keys carry one or more scopes that restrict which API operations they can perform. You choose scopes at key-creation time and cannot add scopes later — create a new key if you need broader access.

Scope	Grants access to
`profiles:read`	GET profile endpoints — list, get, ask, attribution
`profiles:write`	POST /v1/profiles/lookup and lookup/stream, refresh, corrections
`monitoring:read`	List/read monitors and their change history
`monitoring:write`	Create/update/delete/pause/resume monitors
`webhooks:manage`	Inspect/retry/replay webhook deliveries, test endpoints
`account:read`	Read account details, usage, invoices, and API key metadata
`account:admin`	Manage API keys and account settings

Warning: profiles:read alone is not enough to run a lookup — reading a profile and generating one are different permissions. POST /v1/profiles/lookup requires profiles:write; a key with only profiles:read gets a 403 INSUFFICIENT_SCOPE.

Tip: Follow the principle of least privilege. A backend enrichment job that only reads existing profiles needs profiles:read; one that generates new lookups needs profiles:write too.

Test vs. live keys

	Test keys	Live keys
`Billing`	Not counted	Counted against your plan
`Rate limits`	Generous (dev-friendly)	Tier limits enforced
`Data freshness`	May serve cached/stub data	Always real data
`Recommended for`	Development, CI, staging	Production

Key rotation best practices

Rotate on a schedule. Even if a key hasn't been compromised, rotating every 90 days limits the blast radius of any future exposure.
Use environment variables. Never hard-code keys in source code. Use LUMEN_API_KEY in your environment and load it at runtime.
Rotate without downtime. Create the new key first, deploy it, then revoke the old one — not the other way around.
Label keys by purpose. "Production API v3" is easier to track than "Key 1". Use the name field to record the service and date created.
Revoke immediately on compromise. Use the API keys page or DELETE /v1/account/keys/{id} — revocation takes effect in under 60 seconds.

Errors

HTTP status	Code	Meaning
`401`	UNAUTHORIZED	Missing or malformed Authorization header
`401`	INVALID_API_KEY	Key does not exist or has been revoked
`403`	ACCOUNT_SUSPENDED	Account is suspended — contact support
`403`	FEATURE_NOT_AVAILABLE	Key's scope doesn't permit this operation