Developers — API keys, webhooks, OAuth & payments

Finocket's developer platform lets your own products, scripts and AI tools work your books over a versioned REST API. Everything lives under Developers: products, scoped API keys, OAuth clients, webhooks, payments onboarding, request logs and a live API reference. Every call is workspace-scoped by row-level security.

How do I get started with the API?

1. Open Developers — the overview shows your keys, webhooks and recent API activity at a glance.
2. Register a product under Developers → Products — a named container for what you're building (your app, an internal script, an AI agent). Keys and webhooks hang off it.
3. Create an API key under Developers → Keys. Pick live or test mode and tick exactly the scopes it needs — there are 17, from invoices:write to reports:read — nothing more.
4. Copy the key immediately. It is shown once, at creation, then never again. Send it as Authorization: Bearer dmfy_live_… on every request to /api/v1/*.

Writes are idempotent where it matters: creates dedupe on your own external_id or an Idempotency-Key header, so a retried request never acts twice.

What can the API do?

The /api/v1 surface covers the whole business: clients and their ledgers, invoices (create, send, remind, PDF, payments, cancel), payments and refunds, payment links, subscriptions, expenses, items and live stock, sales and purchase orders, CRM (contacts, deals, pipelines, tasks), consent records, partner commissions — plus read-only reports: trial balance, P&L, balance sheet, ageing, GSTR-1/3B/2B/9, day book, Tally XML and more. Running several companies? Send X-Company-Id to pick one per request, or pin the key to a company at creation.

How do webhooks work, and how do I verify them?

1. Register an HTTPS endpoint under Developers → Webhooks and pick events — invoice.created, payment.recorded, stock.low and more, or all.
2. Finocket POSTs JSON with the event name, timestamp and data. Failed deliveries retry with exponential backoff (up to six attempts).
3. Verify every delivery: read the X-Demystify-Signature header (t=<timestamp>,v1=<signature>), recompute HMAC-SHA256(secret, timestamp + "." + rawBody) with your endpoint's secret, compare in constant time, and reject stale timestamps to block replays.

When should I use OAuth instead of an API key?

When a whole product — not one script — needs access. Create an OAuth2 client under Developers → OAuth; it uses the client-credentials grant: exchange client id and secret at POST /api/oauth/token for a short-lived bearer token carrying only the scopes you granted. Revoke the client and its tokens stop working.

Can I collect payments for my own customers?

Yes — Developers → Payments onboards sub-merchants under the aggregator model (powered by Razorpay). Register a sub-merchant, and money settles directly to their bank account — it never passes through your books or Finocket's. You get payment links and status webhooks per sub-merchant.

Where do I debug and explore?

• Developers → Logs — every API request and webhook delivery attempt, with status and timing.
• Developers → Reference — a live Swagger playground: authorize with your key and fire real requests from the browser. The OpenAPI spec is at /api/v1/openapi.json.
• Developers → Docs — the guided walkthrough, including MCP setup so AI agents (like Claude) can use your books as tools.
• Developers → Environment — the reference list of configuration names the platform uses (names only, never values).

Related: Modules & plans, Usage & activity.