Integrate API
Named integrations proxying data, notification and workflow calls to third-party systems.
For concepts and configuration see the block documentation.
Endpoints
Section titled “Endpoints”| Endpoint | Purpose |
|---|---|
GET /list | Integrations available to this tenant |
POST /integration/{name}/data | Proxy a data call |
POST /integration/{name}/notification/{template} | Send through the integration |
POST /integration/{name}/workflow/{workflow} | Trigger a process in the target system |
{name} is the integration’s declared name. Your code knows that and the payload shape; it
does not know the URL, the auth scheme or the token — those resolve at the boundary.
The three shapes
Section titled “The three shapes”Data forwards your payload to the integration’s configured endpoint with its credentials attached. The response is the vendor’s, passed back.
Notification sends using one of the target system’s templates. Distinct from Notifications, which owns delivery for channels the platform manages — reach for this when the other side owns the template and the sending.
Workflow triggers a named process in the target system. Fire-and-forward: the target owns the outcome.
Discovering what exists
Section titled “Discovering what exists”GET /list is the inventory, and it is accurate because it is what the runtime resolves
against — unlike a wiki page listing what someone believed was connected in March.
Credentials
Section titled “Credentials”Credentials resolve from Vault at the integration boundary and are never held by calling code. A credential failure is a distinct condition from a vendor outage and worth alerting on separately — the fix is different and faster.
Tenancy
Section titled “Tenancy”Every request carries the platform tenancy headers — X-Kis-Tenant, X-Kis-Product and
X-Kis-Environment. They are the partition key for storage, quotas and audit, so a request
without them is rejected rather than served against a default tenant.
Errors
Section titled “Errors”Errors use the platform’s structured error body: a stable code, a human-readable message, and the request id to correlate against logs and audit.
Authentication
Section titled “Authentication”Every route requires a bearer token. The health and readiness probes are the only unauthenticated surface.
How a request is resolved
Section titled “How a request is resolved”Each /integration/:name/* route resolves the named integration before doing anything else, so two
failures happen before your call is even proxied:
| Condition | Result |
|---|---|
| No integration by that name | 400 with the error envelope |
| The integration exists but is not active | 400, naming the integration |
Check GET /list when a call fails immediately — an inactive integration looks like a bad request,
not a disabled feature.
Retired routes
Section titled “Retired routes”The four /integration/:name/data methods return 410 Gone:
{"error":"v1 data API retired; migrate to v2"}They are still registered so the failure is explicit rather than a 404. Use the Data API directly.
Tenancy
Section titled “Tenancy”The four CPET headers scope integration lookup and everything proxied through it.
Errors
Section titled “Errors”| Status | Meaning |
|---|---|
400 | Unknown or inactive integration, or a request the proxied service rejected |
401 | Missing or invalid token, as plain text |
410 | A retired v1 data route |
500 | The proxied service failed |
A 500 usually originates downstream — the notification, workflow or BFF target — rather than in
this service.