Skip to main content

Providers & BYOK Routing

Keeptrusts routes traffic through connected gateways. You add provider keys to your organization, tag the resources that should use them, and validate access before you send production traffic.

Free organizations start BYOK-ready. You do not receive included managed credits on Free, so the fastest path to first traffic is:

  1. add a provider key
  2. tag the provider key, agent, and gateway/configuration
  3. attach a provider-access role through the authenticated API
  4. simulate policy access through the authenticated API
  5. send traffic through the connected gateway

Connected gateways only​

The billing, provider-key, and policy flows in this guide assume a connected organization. Keeptrusts resolves provider access from organization resources, not from ad hoc local environment fallback.

That means you should treat these resources as the source of truth:

  • Provider keys in the organization secret store
  • Resource tags on provider keys, agents, gateways, and configurations
  • Policy bindings that grant an agent access to a tagged provider key

Free starts BYOK-ready​

The console Free BYOK onboarding panel in Secrets provides the reachable provider-key setup step:

  1. Choose Configure to add a provider key, or Rotate for an existing key.
  2. Apply resource tags to align the provider key, agent, and gateway/configuration with dimensions such as environment, team, or owner.

The current console does not render its provider-key role-binding and Simulate access component on any agent page. Complete those two checks with the authenticated API described below; do not look for an agent-detail panel that is not currently reachable.

You can start using Keeptrusts on Free without changing plans, but you still need a valid provider key before traffic can route.

BYOK requests and wallet reserve​

When a connected gateway request resolves to a deployed agent linked to the gateway and is BYOK-ready, Keeptrusts still applies the normal wallet reserve/settle flow before provider dispatch when wallet controls and pricing data are in play.

That means:

  • Traffic is rejected when the request cannot resolve to a deployed agent rollout linked to that gateway.
  • If the organization wallet cannot reserve the estimated cost, the gateway returns the insufficient-balance path before the upstream call is sent.
  • If a provider key is missing or policy denies access, the gateway returns the provider readiness or authorization error instead of routing the call.
  • BYOK routing and managed billing are separate concerns, but BYOK readiness does not bypass wallet enforcement.

What the current surfaces show​

The reachable Free BYOK onboarding panel shows Configure when no key is present and Rotate when a provider key exists. It does not display a routing readiness status.

The provider-key simulation API returns raw status values such as ready_byok, ready_managed, or inactive, together with allowed, decision, status_reason, and the matched policy details. Treat that API response—not a Configure/Rotate button—as the readiness decision.

Attach and simulate access through the API​

The control-plane endpoints are live even though their console component is not mounted. Use an API token with agents:write to attach a role. Simulation requires agents:read and secrets:read.

export KEEPTRUSTS_API_URL="https://api.keeptrusts.com"
export KEEPTRUSTS_API_TOKEN="replace-with-api-token"
export KEEPTRUSTS_AGENT_ID="replace-with-agent-uuid"
export KEEPTRUSTS_ROLE_ID="replace-with-role-uuid"

curl -fsS -X POST \
  "${KEEPTRUSTS_API_URL}/v1/agents/${KEEPTRUSTS_AGENT_ID}/provider-key-access/bindings" \
  -H "Authorization: Bearer ${KEEPTRUSTS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"role_id\":\"${KEEPTRUSTS_ROLE_ID}\"}"

curl -fsS -X POST \
  "${KEEPTRUSTS_API_URL}/v1/agents/${KEEPTRUSTS_AGENT_ID}/provider-key-access/simulations" \
  -H "Authorization: Bearer ${KEEPTRUSTS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"provider":"openai"}'

The binding collection also supports GET; detach a binding with DELETE /v1/agents/{agent_id}/provider-key-access/bindings/{role_id}.

Tag the resources that must agree​

Keeptrusts uses a shared resource_tags model across these resource types:

  • provider keys
  • agents
  • configurations
  • gateways

In practice, tag all relevant routing resources with the same business dimensions:

  • environment=production
  • team=payments
  • owner=ml-platform

When tags line up and your policy grants access, the agent can read the matching provider key.

Tag rules​

  • You can add up to 50 user tags per resource.
  • Tag keys must be unique on a resource.
  • Tag keys are limited to 128 characters and values to 256 characters.
  • Keys that start with keeptrusts: are reserved for Keeptrusts-managed tags.

Provider-key access is policy-bound​

Adding a provider key is not enough on its own. Agents receive provider-key access only through explicit policy bindings.

New organizations start with the default Assistant agent already attached to a seeded Default Agent Runtime role. That role is only a binding target. It does not grant provider-key access until you attach policies to it.

Use the provider-key access API to attach a role (or update the seeded Default Agent Runtime role so it carries the statements you want), run the simulation, and confirm allowed before routing live traffic.

If the simulation reports that no role is attached or policy denied access, fix the binding first. Do not rely on trial-and-error in production traffic.

Manual tags vs declarative tags​

You can edit tags live only on manually managed resources.

If a gateway or configuration is managed declaratively, Keeptrusts blocks live tag edits and asks you to update the resource through its draft/apply flow instead. This keeps runtime tags aligned with the configuration document that owns the resource.

Use this rule of thumb:

  • Manual resource → edit tags in the console
  • Declarative resource → update the draft config, then apply it

Billing and provider readiness are connected​

The Bills page shows the subscription state that affects billing actions:

  • current plan and billing interval
  • seat count
  • latest invoice status
  • current window usage
  • recent billing history
  • payment readiness

If billing checkout is not configured, the console tells you to add a payment method before you can activate or upgrade. Free BYOK routing and paid subscription actions are related, but they are not the same thing:

  • Provider keys decide whether traffic can route
  • Billing readiness decides whether you can activate or upgrade

Cancellation behavior​

Paid subscriptions use scheduled cancellation, not immediate shutdown.

If you cancel:

  • access continues until the end of the current billing period
  • you can resume before that date
  • the subscription ends only when the scheduled date passes

Seeded defaults are not recreated automatically​

Some provider entries start as seeded defaults so you can see the supported BYOK path immediately.

If you delete a seeded default provider key:

  • Keeptrusts records that deletion
  • the provider stays unavailable until you add or rotate a real key yourself
  • Keeptrusts does not recreate the deleted seeded default automatically

If you expected the provider to return on its own, reopen the provider setup flow and create the key again manually.

Next steps​