How the Optifora API works
This page describes the shape of the API: how identity is proven, how versions move forward, what limits a request stays inside, what an error looks like, and how data is exchanged with the outside world.
The product is under development and the API surface is still being completed. A reference document for the endpoints will be published separately; this page carries no address and no sample call, only the mechanics.
Authentication
Every request belongs either to a person or to a registered application. A request without an identity that reaches a protected endpoint comes back unauthenticated.
- Bearer tokenThe access token travels in the request's authorization header. It is signed, and it says only who the request belongs to.
- Short lifeAn access token expires after a period measured in minutes; the length is a deployment setting and defaults to thirty minutes.
- Refresh and rotationA session is extended with a refresh token, and every extension issues a new pair. If a spent refresh token is presented a second time, every session for that person is revoked.
- Permissions are not baked into the tokenThe token carries identity only; what a person may see is asked of the database on every request. A permission that is withdrawn therefore stops working before the token in hand expires.
- Integrator keyA registered application connects with its own key. The plain value is shown once, at creation; what is stored is its digest and the non-secret prefix that lets a key be recognised.
- The organisation grants accessHowever widely used an application is, without a grant recorded by the organisation it sees not one row. The grant is dated, scoped and revocable.
Versioning
- The version lives in the pathEndpoints are published behind a version prefix; today's surface is version one.
- A breaking change opens a new pathAn existing endpoint's contract is not broken in place. An incompatible change is published on a new version path while the old one keeps working.
- The document states its own versionThe reference carries the version number it was generated from; which version you are reading is answered by the document itself.
Environments and limits
The reference declares two environments: production and local development. The root address is handed to an integrator together with their key; it is not published on this page.
- Liveness and readiness are measured separatelyOne endpoint says the process is up; the second sends a real query to the database and confirms it is reachable. Only the second one decides whether traffic should be sent.
- Browser origins are restricted to a listCross-origin requests are accepted only from origins declared in advance; while the list is empty, a cross-origin browser request is refused.
- Body limitA request body may not exceed five megabytes. Large sets travel as a bulk transfer job with its own status record, not as a single request.
- Secrets are not written to the logThe server log keeps no authorization header, no cookie, no password and no national identity number.
Rate limit
The limit is per address and per minute. The default is 120 requests a minute and is set at deployment. What remains is reported in headers on every response.
| Response header | What it says |
|---|---|
| x-ratelimit-limit | The total allowance inside the window. |
| x-ratelimit-remaining | What is left in this window. |
| x-ratelimit-reset | Seconds until the allowance is renewed. |
| retry-after | How many seconds before a retry. Present only on the response that refused the request. |
Once the limit is passed the request is refused and the response says how long to wait, in seconds. A retry is made after that time, not immediately.
Error format
Every error comes back in the same envelope: a short code field for the machine to branch on, and an explanation field for a person to read.
- errorThe short code the client decides on.
- messageThe explanation of what happened.
| Status | Code field | What it means |
|---|---|---|
| 400 | Bad Request | The request does not match the schema. The explanation names the field that is missing or invalid. |
| 401 | unauthenticated | There is no valid identity: no token was sent, it has expired, or it did not verify. |
| 404 | Not Found | No such endpoint, or no such record. |
| 429 | Too Many Requests | The rate limit was exceeded; the response says how long to wait. |
| 5xx | internal_error | An unexpected failure. The detail is not handed to the client; it is written to the server log. |
Pagination
Endpoints that return lists take the same two parameters and return the same counters, so a paging client is not rewritten for each endpoint.
- limitHow many records a page should hold. At least one, at most two hundred; fifty when unset.
- offsetHow many records to skip. Starts at zero.
- totalHow many records match the filters in total.
- countHow many records this response actually carries.
The response also echoes the limit and offset it used; the client reads its position from the answer instead of guessing it.
Data exchange and webhooks
The exchange mode is a setting, not a separate product: every registered application carries the mode it works in on its own record.
| Mode | What it means |
|---|---|
| One way — outbound | Optifora publishes data; the other side reads it or subscribes to events. |
| One way — inbound | The other side pushes data; Optifora validates it and writes it. |
| Two way | Both sides write; the conflict rule is defined in advance. |
| Handshake | Every transfer opens a session: offer, verification, approval, transfer and receipt. The receipt stays with both sides. |
- Events are pushed outA webhook sends the event to the callback address the registered application declared. An event that cannot be delivered stays queued and is retried; it is never dropped silently.
- The same request does not write twiceA write request carries an idempotency key. A second request with the same key creates no second record.
- Every call is measuredWho called, when, with which scope and with what result — all of it is recorded. The same record answers both debugging and the question of who pulled this data.
- Our own apps use the same doorNo privileged second path exists. Our own integration is the proof of the surface an outside developer meets.
The data model for the exchange layer is in place; its endpoints are not published yet. When they are, this section will link to their entries in the reference.
Reference documents
The reference is not written by hand; it is generated from the endpoint schemas. As each endpoint hands over its schema the document fills in by itself, so the document and the behaviour cannot drift apart.
- Today: in preparationSchemas are moving module by module. Before the document is published, every endpoint's request and response will be visible in it.
- Two formats will be publishedA machine-readable OpenAPI document, and a reference page drawn from that same document and browsable in a browser.
- Access is tieredThe overview is open to anyone. The full reference may sit behind a documentation token given to a registered integrator; production keys and callback addresses are not a documentation matter at all — they belong to the application record.
- Address standardTwo references are published and their addresses are fixed: client-api.optifora.com/docs is open, admin-api.optifora.com/docs requires authorisation and is closed to the outside. Neither is live today; the links will be added to this section once they are.
If your integration plan is already clear, write to us from the contact page: you will be among the first told when the surface opens.
Do you have a specific request?
These pages explain how the support process works. If you have a request or a question, write to us from the contact page.
Go to the contact page