Developers — API, webhooks & MCP

Finocket has a developer platform for wiring your own products, scripts and AI tools into your books. Everything lives under Developers: API keys, OAuth clients, webhooks, delivery logs and the interactive API reference. Every call is scoped to your workspace and guarded by row-level security — a key can never read another tenant's data.

API keys and the REST API

Create a key under Developers → API keys and tick exactly the scopes it needs (for example invoices:write without payments:write). The key is shown once, at creation — copy it then. Send it on every request as Authorization: Bearer dmfy_live_….

The versioned REST API at /api/v1 covers about twenty resources:

• Money — clients (with a per-client ledger), invoices (create, send by email, remind, fetch the PDF, record payments, cancel), payments (including refunds), payment links, subscriptions and usage events.
• CRM — contacts, deals (move stage, mark won / lost), pipelines, activities, tasks and tags.
• Compliance & partners — consent records (with proof), partner attributions, commission events, partners and merchants.

Writes are idempotent where it matters: clients and invoices dedupe on your own external_id, so a retried request never creates a duplicate.

OAuth clients

If a whole product (not one script) needs access, create an OAuth2 client under Developers → OAuth. It uses the client-credentials grant: exchange the client ID and secret at POST /api/oauth/token with grant_type=client_credentials and you get a short-lived bearer token carrying only the scopes you granted. Revoke a client any time — its tokens stop working.

Webhooks — and verifying the signature

Register an HTTPS endpoint under Developers → Webhooks and pick the events you care about — invoice.created, invoice.sent, payment.recorded, subscription.updated and more, or all of them. Finocket POSTs a JSON body with the event name, a timestamp and the data. Failed deliveries retry automatically with exponential backoff (up to six attempts), and every attempt shows in Developers → Logs.

Every delivery is signed so you can trust it came from us. To verify:

• Read the X-Demystify-Signature header — it looks like t=<timestamp>,v1=<signature>.
• Recompute HMAC-SHA256(secret, timestamp + "." + rawBody) using the endpoint's secret (shown on the Webhooks page) and the exact raw request body.
• Compare your hex digest to v1 with a constant-time comparison, and reject requests whose timestamp is more than a few minutes old to block replays.

Connect an AI agent over MCP

The same API is exposed as a Model Context Protocol server at /api/mcp, so Claude and other MCP-capable agents can create invoices, send reminders, record payments, work the CRM and read commission balances as tools — each tool enforced by the key's scopes. In your AI client, add a remote (“streamable HTTP”) MCP server pointing at https://<your-app>/api/mcp with your dmfy_live_… key as the bearer token. Copy-paste setup snippets are on Developers → Docs.

Interactive reference & OpenAPI

Developers → Docs is the guided walkthrough; Developers → API Reference is a live playground — authorize with your key and fire real requests from the browser. The machine-readable OpenAPI spec is served at /api/v1/openapi.json; import it into Postman or Insomnia, or generate a typed client for your language.

Related: Modules & plans, CRM & deals.