Your own systems can read Naarvin through its API, with keys that act as service accounts: one role, the companies you choose, and nothing more. Webhooks tell those systems when something happens, a sync, an approval, a posting, with signed events that carry names, ids and statuses, never amounts. A key can never approve, sign off or complete a four-eyes review.
How do API keys work?
Each key is a service account. It gets one role and the companies you choose, within what the person creating it holds, and Naarvin treats its requests like a person's with that role: the same permission checks, the same company scope, the same separation in the database. The list of keys shows when, and from which address, each key was last used.
- A key can never approve, sign off or complete a four-eyes review, never passes a fresh sign-in check, and cannot manage keys or webhooks. Those stay with people.
- It is shown once when created. Naarvin keeps only what it needs to recognise it.
- It can be limited to up to 20 IP addresses or IPv4 ranges, and given an expiry of 30, 90, 180 or 365 days.
- It can have its own requests-per-minute limit and a daily quota. Beyond them, Naarvin answers 429 with the seconds to wait.
- Creating or revoking a key needs the right to manage integrations and a fresh sign-in check.
What can a key read?
Whatever its role allows, for its companies. The documented reads include the income statement, balance sheet and cash-flow statement, key indicators, the trial balance and general-ledger lines, receivables and payables ageing, the cash position and data quality. Periods take a month (2026-06), a quarter (2026-Q2), ytd or a date range, and a scope parameter narrows to some of the key's companies or a group. Amounts come as decimal strings, never rounded floats.
The full OpenAPI 3.1 reference is generated from the API itself, so it lists every route and the permission each needs. Signed-in members can browse it in Naarvin, under Settings, Integrations and API. The same keys power the live formulas in Google Sheets and Excel.
What do webhooks send?
A JSON POST to your HTTPS endpoint for each event you subscribe to: its id, type, time, your organization and a data object of names, ids and statuses. Events never carry amounts; your system can call the API with a key when it needs figures.
| Event type | Sent when |
|---|---|
| sync.completed, sync.failed | A connection finished a sync, or failed |
| approval.requested, approval.decided | An approval was requested, or approved or rejected |
| erp_posting.drafted, erp_posting.posted, erp_posting.failed | A journal or document was drafted for review, posted to the ERP, or refused |
| close.signed_off, close.reopened | A month was signed off or reopened for a company |
| evidence.added | A support file was attached to a close task, reconciliation or auditor request |
| report.sent | A scheduled report went out |
| finding.raised | An agent raised a critical finding |
| audit.anchored, audit.chain_broken | The audit log's chain was verified, or did not hold |
How do you verify a webhook came from Naarvin?
Each request carries a Naarvin-Signature header of the form t=<unix seconds>,v1=<hex>. Compute HMAC-SHA256 over the timestamp, a full stop and the raw body, using the signing secret shown once when you created the endpoint, and compare it with v1. Reject requests whose timestamp is old, so a captured request cannot be replayed. The Naarvin-Event and Naarvin-Delivery headers name the event type and the delivery.
Endpoint addresses and secrets are sealed when saved. Failed deliveries are retried, up to eight attempts; an endpoint that fails 20 times in a row is paused. Recent deliveries can be sent again, and a test event checks your endpoint. See security.
How do you start?
- Create a key for one purposeUnder Settings, Integrations and API, create a key with the narrowest role and the companies the system needs, an expiry, and IP limits if the caller has fixed addresses.
- Read the referenceFind the routes you need and the permission each requires, then make a first call for one company.
- Add a webhook endpointAdd your HTTPS address, pick the events, copy the signing secret and verify the test event.
- Review keys regularlyRevoke keys nobody uses. A revoked key stops working at once.
Questions people ask
Can an API key approve a payment?
No. Keys can never approve, sign off or complete a four-eyes review. Those always need a person.
Why do webhooks carry no amounts?
An event may land in systems and logs outside Naarvin's access rules. Your system reads figures through the API, with a key scoped to the companies it may see.
Can our systems push books into Naarvin through the API?
Books come in through connectors, files, a database login or a [REST data feed](/integrations/rest-data-feed) that Naarvin reads.