Authentication
API keys, accepted header shapes, and scopes
Every request needs an API key. Keys are created at Account → API keys and look like sk-mel-<128 characters>.
Sending the key
We accept both header shapes, so SDKs written against OpenAI or Anthropic work unmodified:
x-api-key: sk-mel-<YOUR_API_KEY>You can use either on any endpoint. Pick whichever your client prefers and be consistent.
Key handling
Keys are shown once. If you lose it, rotate it — there's no recovery button.
A few things to remember:
- Store in an env var —
MELIOUS_API_KEYor your convention. Never commit to version control. - Don't expose keys to browsers. Keep the key server-side and proxy inference calls through your backend. A leaked key costs you tokens, not just lint failures.
- Rotate on suspicion. The dashboard has a one-click revoke + reissue. Prior keys stop working immediately.
- Prefer scoped keys in CI and agents. If a key only needs
inference.chat, don't give it*.
Scopes
Scopes limit what a key can do. When you create a key, pick the narrowest set that covers your use case.
| Scope | Grants |
|---|---|
* | Everything. |
inference.* | All inference endpoints. |
inference.chat | POST /v1/chat/completions and POST /v1/messages |
inference.embeddings | POST /v1/embeddings |
inference.images | POST /v1/images/generations |
inference.audio | POST /v1/audio/speech, POST /v1/audio/transcriptions |
inference.rerank | POST /v1/rerank |
inference.models | GET /v1/models |
kit.* | All kit endpoints. |
kit.tools | /v1/tools/* |
kit.mcp | /v1/mcp/* |
kit.documents | POST /v1/documents/convert |
kit.knowledge.read | GET /v1/vector_stores/*, search |
kit.knowledge.write | POST/DELETE /v1/vector_stores/* |
Matching rules: * is a full pass, inference.* matches any inference.X, exact strings match exactly. A key with no scopes set (empty list) gets full access — legacy keys before the scope system landed work this way, and we kept it for backward compatibility.
Using an endpoint with the wrong scope returns AUTH_1015 (insufficient scope). The error says which scope you need.
Plan benefits
Two plan-gated details worth naming explicitly:
Advanced models. A small set of top-tier models are marked advanced. Keys belonging to plans without the advanced_models benefit get VALIDATION_4003 when they request one. The error says which plan unlocks it. Browse melious.ai/hub to see which models are flagged.
API energy vs credits. Plans without the api_usage benefit are forced to pay requests in credits, not the energy pool. This matters if you mix web and API usage — an API-only plan can't spend energy on API calls, only credits. See Pricing.
Related
Scope violations and other auth-level errors: Errors. How plan tiers map to throughput: Rate limits.