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 a tier above Free 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 tools/call endpoint and return the same response shape. The differences are in the URL path, daily limits, and the user identity attached to the request for billing and audit.
API key requests go to /mcp with a Bearer header. OAuth requests go to /mcp/auth with a Bearer JWT issued by Supabase Auth.