REST API

The REST API is how another system reads from and writes to a d1kit deployment. It suits integrations that need a defined set of operations with straightforward payloads: post a transaction, fetch a balance, look up a record, submit a request.

For richer queries that would otherwise take several round trips, use GraphQL. To be told when something happens rather than asking, use webhooks.

Access is granted, not self-service

There is no public sign-up. Integration credentials are issued per deployment by the organisation that operates it, because the data belongs to them and the decision is theirs.

Each integration gets its own identity with its own permissions, separate from any human user account. That separation matters: an integration credential carries a narrow, stable set of permissions and cannot be used to sign in to the application interface and browse.

Authentication

Callers present issued credentials and receive a time-limited token, which accompanies each subsequent request.

The rules applied to every deployment:

• TLS is required. There is no internal-network exemption.
• Credentials travel in headers, never in a query string - query strings end up in access logs and proxy caches.
• Tokens expire, and expiry is enforced by the server rather than by the client choosing to stop using one.
• Tokens are scoped to the integration they were issued to, and to the permissions that integration holds.

What is exposed

An integration sees exactly the operations it has been granted, over the data its permissions allow. Deployments commonly expose:

• financial transactions, account balances and reporting figures
• inventory positions, movements and item catalogue data
• requests and their approval status
• reference data - accounts, cost centres, locations, categories

The precise operation list is per deployment, because the modules configured differ. The operator provides an integration specification covering available operations, payload shapes and error codes when credentials are issued.

Behaviour you can rely on

Pagination. Every collection response is paged, with a maximum page size enforced by the server regardless of what a caller requests.

Rate limiting. Every integration has a request budget. Exceeding it returns a rate-limit response rather than degrading the deployment for everyone else.

Honest status codes. A validation failure is a 4xx, not a 200 with an error buried in the body.

Machine-readable errors. Failures carry a stable error code alongside a human-readable message, so a caller can branch on the code without parsing prose.

No internal disclosure. Error responses never carry stack traces, query text or internal paths, and a record that exists but is outside the caller’s permissions returns the same response as one that does not exist.

Logged calls. Every request is recorded with its caller, the operation and the outcome. Operators can see an integration’s behaviour without waiting to be told about a problem.

Writing data

Write operations run the same validation and approval rules as the application interface. An integration cannot bypass an approval requirement, post to a closed period, or write outside the scope its permissions define - the interface is a different door into the same rules, not a way around them.

Where a write initiates something requiring human approval, the response tells you it is pending rather than pretending it is complete.

Designing a resilient integration

• Retry with backoff on 5xx and rate-limit responses; do not hammer a struggling deployment.
• Make writes idempotent where the API supports a client reference, so a retry after a timeout does not duplicate a transaction.
• Treat identifiers as opaque. Do not parse meaning out of them or assume a format.
• Handle new fields gracefully. Additive changes should not break your parser.
• Do not poll for changes on a short interval. Subscribe to webhooks instead, and reserve polling for reconciliation.

Getting started

Talk to the operator of the deployment you need to integrate with. If you are evaluating d1kit for a build of your own, get in touch and we will walk through what the interface would expose for your case.