Skip to main content

Building Custom Integrations with the Keeptrusts REST API

The Keeptrusts console and CLI cover most daily workflows, but not every platform needs the same integration shape. Some teams want to push event data into a larger reporting system. Some want deployment verification in an internal dashboard. Some want automated evidence exports or runtime-state checks inside their own tools. That is where the Keeptrusts REST API becomes the right surface: explicit HTTP contracts, scoped authentication, and endpoints that match the operating data the platform already records.

Use this page when​

  • You need programmatic access to events, exports, or configuration state.
  • You are building internal automation that sits beside the CLI rather than replacing it.
  • You need to distinguish between the control-plane API and the gateway’s own request interface.

Primary audience​

  • Primary: Technical Engineers and platform developers
  • Secondary: Technical Leaders building governance automation into larger systems

The problem​

As soon as Keeptrusts becomes shared infrastructure, teams want it to participate in broader platform workflows. Security teams want event data in downstream analysis pipelines. Delivery teams want rollout status visible next to application deployment status. Compliance teams want repeatable export jobs instead of manual evidence gathering. Internal developer platforms want a single place to check gateway configuration state.

The CLI can help with many of those tasks, but service-to-service workflows usually want a direct HTTP contract. They need stable URLs, scoped tokens, and response bodies that can be queried from their own schedulers, dashboards, or workers.

The confusing part for new builders is that Keeptrusts exposes two different HTTP surfaces.

The gateway itself exposes an OpenAI-compatible interface, such as /v1/chat/completions, for governed model traffic. The control plane exposes REST endpoints like /v1/events, /v1/exports, and /v1/admin/configurations for operational and administrative data. Custom integrations become cleaner as soon as that distinction is explicit.

The solution​

Build custom integrations around the surface that matches the job.

If you need governed model traffic, integrate with the gateway endpoint. If you need observability, evidence, rollout state, or administrative data, integrate with the control-plane API using a scoped Keeptrusts token. Use the CLI when it is the easiest way to mint or manage those tokens, and use HTTP when the workflow needs to be embedded in another system.

That hybrid model is usually the right one. The CLI remains the operator tool. The REST API becomes the system-to-system interface.

Implementation​

Start with scoped authentication. For automation, create a token once and store it in your secret manager:

kt auth token create --name integration-reader --scope team --role-id role_configurations_writer

Then use the token as a normal bearer token from your integration runtime:

export KEEPTRUSTS_API_URL="https://api.keeptrusts.com"

curl -fsS \
  -H "Authorization: Bearer $KEEPTRUSTS_API_TOKEN" \
  "$KEEPTRUSTS_API_URL/v1/events?since=24h&limit=50"

That single pattern is enough for a surprising number of internal tools. A dashboard job can summarize recent blocks. A nightly workflow can compare event volume day over day. An incident bot can pull the newest blocked or escalated decisions into a case-management system.

When you need a durable evidence artifact rather than a live query, use the exports endpoint:

curl -fsS -X POST \
  -H "Authorization: Bearer $KEEPTRUSTS_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$KEEPTRUSTS_API_URL/v1/exports" \
  -d '{
    "format": "json",
    "time_window": {
      "since": "2026-05-01T00:00:00Z",
      "until": "2026-05-31T23:59:59Z"
    }
  }'

This is a better fit for compliance workflows and scheduled archival because it turns a time-bounded evidence request into a durable output instead of a transient query result.

For deployment visibility, query configuration state directly:

curl -fsS \
  -H "Authorization: Bearer $KEEPTRUSTS_API_TOKEN" \
  "$KEEPTRUSTS_API_URL/v1/admin/configurations"

That is useful when your internal platform wants to display gateway health and running versions alongside application release data.

The gateway interface is the other half of the story. When your integration wants governed model traffic, point it at the gateway instead of the upstream provider:

curl -fsS http://localhost:41002/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {"role": "user", "content": "Summarize the latest blocked decisions."}
    ]
  }'

That request goes through the same policy chain as any other governed client. The integration does not need to know how the enforcement logic works internally. It only needs to target the correct endpoint.

One strong design pattern is to keep these two surfaces separate in your codebase.

  • A data-plane client sends governed requests to the gateway.
  • A control-plane client queries events, exports, and configuration state.

That boundary makes permissions easier to reason about and prevents accidental coupling between traffic enforcement and operational reporting.

Another practical pattern is to use the CLI and REST API together. The CLI can create or rotate tokens, while the API powers the long-running integration. That keeps token lifecycle in an operator-friendly surface without forcing your internal service to shell out for every request.

Results and impact​

Teams that build against the Keeptrusts REST API usually get better fit with their broader platform workflows because they stop forcing everything through a human-oriented interface. Operational data becomes queryable, export workflows become schedulable, and governed traffic becomes easy to embed in custom tooling.

The bigger gain is architectural clarity. Once the gateway and control plane are treated as separate HTTP concerns, integrations become simpler to secure and easier to maintain.

Key takeaways​

  • Keeptrusts exposes both a governed gateway HTTP interface and a control-plane REST API, and they solve different problems.
  • Use scoped bearer tokens for automation instead of interactive login.
  • Query /v1/events for recent decision data and POST /v1/exports for durable evidence artifacts.
  • Use /v1/admin/configurations when internal tooling needs rollout or runtime-state visibility.
  • Keep data-plane and control-plane clients separate in your own integrations.

Next steps​