API keys
API keys (called ingestion keys in the dashboard) authenticate both the Ingestion API and the Data API.1
Open Settings → Ingestion keys
Creating and revoking keys requires the admin or owner role. All members can view the key list.
2
Create a key
Click New ingestion key and name it. Keys never expire unless you set an optional expiry date.
3
Copy the key now
The full key is shown once, at creation. Afterwards the list shows only the key’s name, prefix, creation date, age, last-used date, and expiry.
moda_sk_ and are bound to the workspace they were created in. A key cannot be moved or re-pointed to another workspace — the server derives the workspace from the key on every request.
Which header to use
The two APIs read different headers. Sending the wrong one returns401.
The Ingestion API also accepts the bare key in the
Authorization header, without the Bearer prefix.401 with {"success": false, "count": 0, "message": "Missing Authorization header", "requestId": "..."}; a revoked, expired, or malformed key returns 401 with "Invalid or expired API key".
Data API example:
moda.init() reads the MODA_API_KEY environment variable; the Node.js SDK’s Moda.init(apiKey, options) requires the key as an explicit argument. See Python and Node.js.
Key expiry
Keys do not expire by default. To limit a key’s lifetime, set an expiry date when you create it; the key stops working at the end of that day, in your browser’s time zone. An expiry cannot be changed later. Expired keys stay in the list, marked Expired, and are refused by both the Ingestion API and the Data API with the same401 as a revoked key. Rotate a key before it expires so ingestion does not stop: create the new key and deploy it everywhere first.
Revoking a key
Revoke keys in Settings → Ingestion keys (admin or owner role).CLI authentication
The CLI uses two credentials:- CLI session —
moda auth loginopens the browser; signing in creates a CLI session used by setup and control commands such asmoda initandmoda provision.moda auth statusshows the current session (exit code 4 when logged out);moda auth logoutrevokes it. - API key — Data API commands (
moda traces search,moda overview,moda detections list --family=emotion,moda problems get,moda tail, …) use an API key, not the session; this includes the write commandsmoda problems feedbackandmoda problems link. The CLI resolves the key in this order: theMODA_API_KEYenvironment variable, then the active profile, then~/.moda/config.json.
Headless and CI: moda provision
moda provision mints (or reuses) a workspace API key without any prompts and prints exactly one JSON document to stdout:
moda auth login on a machine with a browser first, then provision. Typical use for CI is provisioning locally and storing the key as a CI secret:
- Exit code 4 when no CLI session exists.
- Exit code 5 when your account belongs to multiple workspaces and neither
--tenant-idnorMODA_TENANT_IDselects one. --labelnames the key (defaults to the hostname);--savepersists the credentials to~/.moda/config.json;reused: truemeans an existing key was returned instead of a new one.
Next steps
- Ingestion overview — where the Bearer header is used.
- Data API overview — where the
x-api-keyheader is used. - Team — the roles that gate key creation and revocation.
- Limits — request and query limits across both APIs.