Browser dashboards are for people. Revenue platforms also need machines.
Your ERP wants to top up a wallet after a bank transfer clears. A partner app wants to report that a consultation happened. A billing bot wants to open a dispute with the same evidence a human would upload.
Those are not “nice-to-have scripts.” They are how Finno joins the rest of your stack — without handing out an operator’s session cookie, and without putting money APIs on the Raft control plane.
Integration clients are Finno’s answer: machine credentials into the same routes the panel already serves.
Not a parallel API
An integration client is a second credential path, not a second product surface.
On success, machine auth produces the same session claims and admin scope the cookie path produces. Every existing handler keeps working. authorize_path stays the single authorization function. Panel and API cannot disagree about who may do what.
That matters when money moves. A “convenience” machine API that drifts from the UI is how you get two truths about the same wallet.
Why signatures, not bearer tokens
These clients move money. A bearer token that anyone can replay after observing it is the wrong tool.
Finno requires an HMAC over the method, full request target (including query), body hash, and timestamp:
X-Finno-Key-Id— which credentialX-Finno-Timestamp— must be within ±5 minutes of our clockX-Finno-Signature—v1=<hex>over a canonical string
A captured signature is bound to its own contents. It cannot be replayed against a different amount, a different consumer, or a different endpoint. Binding method and path is exactly what body-only webhook signing does not do — and it is the difference between a captured GET and a forged POST.
Unknown key, inactive client, bad signature, and address outside allowed_cidrs all refuse the same way. Probing key ids teaches an attacker nothing useful.
Default-deny scopes and consumer reach
Scopes are derived from the request path as <resource>:<read|write>. Coarse on purpose: a finer grammar goes stale when routes are added, and a stale authorization table fails open.
A new resource under /v1/ is denied until someone grants it. A client with no scopes reaches nothing. :write implies :read on the same resource. Credentials cannot mint or widen other credentials — integration-clients is not a grantable scope.
Reach is separate from scope:
- granted (default) — only consumers explicitly linked to the client
- all — every consumer, for carefully chosen operators
Reach fails closed. An integration that cannot prove its reach does not get the benefit of the doubt over someone else’s money.
Two surfaces, two authentications
| Surface | Port | What it does | Auth |
|---|---|---|---|
| Dashboard API | :9090 | CRUD, deposits, invoices, adjustments, disputes, reports | HMAC-signed request |
| Gateway | :8080 | Metered traffic, including virtual services | Consumer gateway credential + optional Ed25519 attestation |
One integration-client row can carry both: an HMAC secret for the dashboard and a registered public key for gateway attestations.
Virtual services: meter what Finno does not deliver
Some products are priced like API calls but happen outside Finno entirely — a consultation, a field visit, a ticket closed in another system.
Virtual services let a third-party reporter declare units on the gateway hot path. Finno reserves, finalizes, and accounts the same way it does for proxied traffic. The service is real money with a real ledger trail; Finno simply is not the delivery pipe.
That is also why disputes matter later: when the report — not the arithmetic — is contested, you need a reconciliation path, not a spreadsheet war.
What this unlocks
- Wallet top-ups and invoice flows from ERP / CRM without a human in the loop
- Partner platforms acting only for the consumers you grant
- Reporting of off-platform delivery that still lands in Finno’s books
- The same maker/checker and dispute machinery operators already use — now callable by automation
What to ask your team
If another system needs to move Finno money today, do you hand it a browser session — or a scoped, signed, rotatable credential?
See how Finno fits your stack or talk to us about a technical evaluation.