Skip to main content
Minerva is the single entry point. The only credential you need is your API key.

​
Where to get your API key

1

Sign in

Log in at app.minerva.io (not available on the free tier).
2

Open Settings

Click your org name in the bottom-left → the three dots (...) → Settings.
3

Open the API tab

Open the API tab and copy your key. Treat it like a password.

​
Use it

VariableUsed for
MINERVA_API_KEYevery call the SDK makes
from minerva import Minerva

mc = Minerva()                          # api_key from MINERVA_API_KEY env
mc = Minerva(api_key="mk_live_...")     # explicit

​
Resolution order

1

Constructor argument

Minerva(api_key="mk_live_...")
2

Environment variable

MINERVA_API_KEY
If neither is set, the first call raises MinervaAuthError("no API key (set MINERVA_API_KEY or pass api_key=).").

​
How it’s sent

The SDK sends the API key as the x-api-key header on every request. There’s no token exchange, no session state, no rotation handled by the SDK — your long-lived API key is the only credential. The server-side authorizer decides what your key is entitled to. 
POST /v2/enrich
x-api-key: mk_live_...
Content-Type: application/json

{ "records": [ ... ] }

​
Rotating your key

Rotate your key in the Minerva web app. Once rotated:
  • The old key continues working for the documented grace period (check your plan)
  • Update MINERVA_API_KEY in your deployment / secret store
  • Restart the process so a fresh Minerva() picks up the new value

​
Errors you might see

ErrorMeaning
MinervaAuthError("no API key …")Neither api_key= nor MINERVA_API_KEY set
MinervaAuthError from a server response401 / 403 — your key is invalid, revoked, or not entitled to the endpoint you called
MinervaRateLimitError(retry_after=…)429 — you’re rate-limited; back off and retry
See Error handling for the full hierarchy.