API reference
Client protocol
The wire contract between clients and the middleware: authentication, method invocation and the admin endpoints.
Note
Kiwi Distro is currently in private preview. Interfaces and behaviour described here can change before general availability. Contact Kiwify Labs for access.
This is the contract every client SDK implements. Reference SDKs are available for Node.js (the reference implementation), Python and Java, and the .NET SDK is Kiwify.Kiwi.Distro.Client.Native.
Authentication#
POST {middleware_url}/client/auth_token is anonymous and form-encoded.
grant_type=client_credentials&client_id=<id>&client_secret=<secret>
grant_type=refresh_token&client_id=<id>&refresh_token=<rt>&auth_token=<current access token>
A 200 response contains requester_id, access_token (a JWT), refresh_token, expires_in and expiration_time. Send Authorization: Bearer <access_token> on every other call, refresh about five minutes before expiry, and fall back to a fresh client-credentials grant if a refresh fails.
Method requests#
POST /client/api/request (synchronous) and POST /client/api/submit (fire and forget) take a MethodRequest:
| Field | Notes |
|---|---|
method |
Required, "<service>/<method>" |
target |
any (default), all or a worker id |
ttl |
Optional, for example 30S |
filter |
Optional tag filters, AND-combined: { tag, operator (eq, ne, in, nin, like), value: [..] } |
params |
Method arguments |
callback, callback_timeout |
Submit only: the result is posted to this URL |
feedback_callback |
Submit only: progress feedback is posted here |
version |
Optional: pins a deployment version |
Single-target response: { "status": "success", "result": ... } or { "status": "failed", "error": "..." }.
target: "all" response: { "status": "success" | "partial" | "failed", "results": [ { "worker_id", "status", "result" | "error" } ] }.
submit returns the request id as a JSON-quoted string. Fetch the result with GET /client/api/result/{requestId}, which returns the same envelope with "status": "pending" while it is not ready.
A method that ran and failed is reported on the envelope. A 4xx or 5xx (bad request, authentication or authorisation failure, no capable worker 503, store timeout 503) is a real error.
Admin endpoints#
All require a bearer token. List endpoints take a filter object via POST .../getAll.
| Area | Endpoints |
|---|---|
| Services | /client/service/create, update, getAll, getOne/{id}, delete/{id}, secrets, remove_secrets; {id}/deployment_strategy, {id}/swap_blue_green, {id}/feedback_handlers |
| Service-to-service authorisation | {id}/allowed_callers, {id}/method_restrictions and .../{methodName} |
| Clients | /client/create (returns a one-time client_secret), getAll, getOne/{id}, enable/{id}, disable/{id}, delete/{id} |
| Client authorisation | /client/{id}/allowed_services, allowed_service_groups, groups |
| Service groups, client groups | /client/service_group/* and /client/client_group/* (create, get, members or grants, delete) |
| Workers | /client/workers/getOne/{id}, getAll, /client/middlewares |
| Worker profiles | /client/workerProfile/create (returns a one-time auth_secret), getAll, enable/{id}, disable/{id}, delete/{id} |
| Secrets | /client/secrets/store, getAll, getOne/{key}, delete/{key} |
| Feedback | GET /client/feedback with optional worker_id, request_id, worker_tag, feedback_type, page, page_size, sort |
| SideCar | /client/sidecar/mappings/{serviceId} |
| Scripts and executors | /client/scripts/*, /client/executors/* |
Secrets#
A secret's type is "i" (internal, the literal value, delivered to a worker as is) or "x" (external, a reference such as an ARN that the middleware resolves when a worker registers). A service attaches secrets by name, and the middleware hands the values to the worker as application settings.