Authentication
Generate API keys, sign requests, and understand token scopes.
All Lumeo API requests are authenticated with a Bearer token issued from the developer portal or via the OAuth exchange endpoint. There are two token types: API keys (long-lived, server-to-server) and session tokens (short-lived, user context).
Getting an API key
- Sign in at lumeo.co.in and open Settings → Developers → API Keys.
- Click New key, give it a name, and choose an environment (Sandbox or Production).
- Copy the key immediately — it is shown only once.
Sandbox keys are prefixed sk_sandbox_. Production keys are prefixed sk_live_.
Using your key
Pass the key as a Bearer token in the Authorization header on every request:
curl https://api.lumeo.co.in/api/v1/payments/initiate \
-H "Authorization: Bearer sk_sandbox_..." \
-H "Content-Type: application/json"const lumeo = new LumeoClient({ apiKey: process.env.LUMEO_API_KEY! });Key scopes
Keys are issued with the minimum scope required. When creating a key from the portal, select only the scopes your integration needs.
| Scope | Allows |
|---|---|
payments:write | POST /payments/initiate, POST /payments/confirm |
payments:read | GET /payments/payouts, GET /payments/payouts/:id |
compliance:read | FIRA fetch, GST summary, ITR-4 prefill |
ledger:read | Account balances, ledger entries, reconciliation status |
tax:read | Tax liability, ITR-4 prefill exports |
webhooks:manage | Register and rotate webhook endpoints |
Rotating and revoking keys
- Rotate: In the portal, open the key and click Rotate. A new key is issued immediately; the old key remains valid for a 24-hour grace period so you can deploy the replacement without downtime.
- Revoke: Click Revoke to invalidate a key immediately. There is no grace period on revocation — use rotate if you need continuity.
Never expose keys client-side
API keys must only be used server-to-server. Do not include them in browser bundles, mobile apps, or public repos. Use environment variables and a secrets manager (e.g. Doppler, AWS SSM, Vercel Environment Variables) to inject them at runtime.
Idempotency
Mutating endpoints (initiate, confirm) accept an Idempotency-Key header containing a client-generated UUID. Retrying the same call with the same key returns the original result without creating a duplicate:
curl -X POST https://api.lumeo.co.in/api/v1/payments/initiate \
-H "Authorization: Bearer sk_sandbox_..." \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{ ... }'Idempotency keys are scoped to your API key and expire after 24 hours.