This guide is for developers and software companies who want to build an integration between Keito and another platform, especially one that several customers will use. It explains how to start the conversation, how authorisation works today, how to work with invoices safely, and which capabilities you should not assume exist.
Who this is for
- You operate or plan to operate a connector between Keito and an accounting, payments or operations platform.
- Your integration will act for one Keito customer first and may later serve many.
- You need to know who authorises access, how it is revoked and who supports it before you write code.
If you are automating your own workspace, the Keito API quickstart and the authentication guide are the right starting points instead.
How to start
Apply through the Integration Partner track. A short technical summary makes the first conversation productive. Include:
| Topic | What to describe |
|---|---|
| Operator | The company that will run and support the integration, with a technical and a security contact |
| Workflow | The customer problem, which records move and in which direction |
| System of record | Which system owns each record (for example Keito for invoices, the accounting platform for ledger postings) |
| Access | The read and write actions you need, kept to the minimum the workflow requires |
| Customers | Whether the integration serves one customer or many, and how each customer would authorise it |
| Operations | Expected volume, polling intervals, retry strategy, idempotency for accounting writes, and how you monitor failures |
| Policies | Where customers can read your support, privacy and service terms |
Do not send credentials, customer lists or financial records with your application. If we need technical access details later, we will arrange a secure way to share them.
Authorisation today
Keito supports two kinds of API credential and documents them in the authentication guide:
- Full-access integration keys are created by a workspace administrator and bound to a chosen member or Agent identity. They act with that identity’s current permissions, never with implicit administrator access.
- Personal read-only sync keys let one person export their own time and read a small, fixed set of endpoints. They cannot create, edit or delete data and are not suitable for invoice or payment operations.
Some partner integrations use OAuth through WorkOS Connect instead of API keys. These connections belong to the workspace and user who authorised them, enforce current permissions on every request, and require reauthorisation after relevant access or security changes.
A reusable integration that several customers install needs its own approved app identity, with a separate authorisation for each customer workspace that the customer can inspect and revoke. That path is agreed during the Integration Partner review. Self-service app registration is not offered, and one customer’s credentials must never be reused for another customer. Do not design around sharing an administrator’s personal credentials.
Working with invoices
The Invoices API covers the records most accounting integrations need:
- Polling for changes. List invoices with the documented filters and an
updated_sincelower bound. Use an overlap window between polls so an update that lands during a poll is not missed, and page through results until the response is empty. - Clients. Map Keito client IDs to the identifiers in your platform explicitly. Do not match customers on name alone.
- Recording payments. Record a partial or full payment against a non-draft invoice with an
Idempotency-Keyheader so a retried request cannot record the same payment twice. Setsend_thank_youtofalsewhen the connector must never send customer email. - Keep your own ledger. Listing invoice payments is not yet available over the API, so your connector should retain its own record of every payment it has written, including the external transaction reference, and reconcile against invoice balances before retrying an uncertain write.
Treat draft, void and refunded invoices as distinct states. Export only the invoice states the customer has approved, and fail closed when permissions change, the workspace does not match, or an invoice is in an unexpected state.
Testing
Agree a test setup with us before connecting a customer’s live accounts. We will confirm what is available for your integration, which environment it runs in and the access conditions during technical onboarding. Do not assume that a public or self-service test environment exists, and never test against a customer’s live books.
Support boundaries
- Keito supports its platform and API, including authorisation and authentication failures, API defects and platform incidents.
- The integration operator supports the connector: setup, field mapping, retries, customer onboarding, its own billing and first-line troubleshooting.
- The customer authorises access, validates mappings and accounting outcomes, and decides when to go live.
Escalation routes between Keito and the operator are agreed before any production connection.
What is not available
- Self-service OAuth app registration through the website.
- A public or self-service test environment.
- Listing invoice payments over the API.
- Public listing of an integration before it has completed production review and the operator has given permission to publish.
If you are unsure whether a capability exists, ask through the Integration Partner track rather than building on an assumption.