Guide
API key vs OAuth
Lumin supports both. Pick by the question, not the convenience.
Use an API key when
- You are building a service-to-service integration where Lumin runs on behalf of the application, not a specific user.
- Your usage is bursty or scheduled, and you want a fixed credential rotated by the operator.
- You want your application's usage on one meter, topped up with call packs, without OAuth orchestration overhead.
- You are testing or scripting and need a single header to copy around.
Use OAuth when
- The integration runs on behalf of an end user who has their own Lumin account.
- You need per-user usage attribution and budget enforcement.
- You ship a public client (Claude.ai, an MCP-aware browser extension) that needs claude.ai to handle the consent flow.
- You want short-lived tokens and refreshable sessions instead of long-lived keys.
What changes downstream
Both auth modes hit the same /mcp endpoint, use the same tools/call shape, and return the same response. The differences are which monthly allowance the call is metered against and the identity attached to the request for billing and audit.
An API key goes in as Authorization: Bearer mcp_.... An OAuth request carries a Bearer access token issued by Lumin, after the user signs in with an email address and a six digit code. Neither is optional: a request with no credentials is rejected.