Skip to main content

API Tokens and Authentication for IDE Integration

An IDE workflow can involve three credentials. They have different owners and must not be reused interchangeably.

CredentialUsed bySent to
Gateway runtime tokenkt gateway runKeeptrusts control plane
Client API tokenIDE model client or MCP clientKeeptrusts gateway
Provider credentialGateway provider targetUpstream model provider

Access Keys and Gateway Keys are filtered views of the shared Keeptrusts API token system. Manage them on the console's API Tokens page.

Before configuring a client​

Have these values ready:

  • the exact model base URL or published MCP hostname you intend to use
  • a client token whose role, expiry, model restrictions, and budget match that workload
  • the separate gateway runtime and provider credentials on the machine that runs kt gateway run

Start with one narrowly scoped client token. Verify the real client flow before issuing tokens to a team.

Gateway runtime token​

The gateway process reads its runtime credential from KEEPTRUSTS_API_TOKEN or --api-token. It uses that identity for configuration, registration, telemetry, and relay connectivity. Do not copy it into an IDE.

Model-client token​

Create a separate token for each developer, team, or automated IDE workload. Use the narrowest roles, model restrictions, budgets, and expiry that fit the workflow. The token is sent as:

Authorization: Bearer <client-api-token>

OpenAI-compatible clients usually label this field API key. Enter the Keeptrusts client token there when the base URL points at the gateway. Provider keys belong in the gateway's secret_key_ref, not in that client field.

MCP-client token​

The hosted /mcp route also requires a Keeptrusts API token. Store it through the MCP client's supported secret mechanism:

  • Codex: --bearer-token-env-var
  • VS Code: a password input variable in mcp.json
  • Cursor and Windsurf: environment interpolation in the MCP header
  • clients with a secure settings UI: the operating-system keychain

For example, Codex can reference the token without copying its value into the client configuration:

export KEEPTRUSTS_MCP_TOKEN="<mcp-client-token>"
codex mcp add keeptrusts \
  --url "https://<published-hostname>/mcp" \
  --bearer-token-env-var KEEPTRUSTS_MCP_TOKEN

If you have a Keeptrusts repository checkout, its optional installer can write supported client configuration for you:

export KEEPTRUSTS_MCP_TOKEN="<mcp-client-token>"
./scripts/install-mcp.sh \
  --hostname "<published-hostname>" \
  --token-env KEEPTRUSTS_MCP_TOKEN

Safe storage​

  • Never commit a raw token to source control.
  • Prefer the client's secret store or OS keychain.
  • If a GUI client reads an environment variable, ensure the variable is available to the GUI process, not only to an interactive shell.
  • Rotate a token immediately if it appears in logs, screenshots, or a committed file.

Rotation​

  1. Create the replacement token with the intended restrictions.
  2. Update one client and verify the real IDE flow.
  3. Update the remaining clients.
  4. Revoke the old token.

Keep the old and new token names visible during the transition so request Events from kt events or GET /v1/events with required since, together with token metadata, show which credential produced each decision. When History capture is enabled for the flow, History adds the retained session context; it is not the universal credential-correlation source.

Troubleshooting​

For 401, verify the raw bearer value, token status, expiry, and the client process's environment. For 403, inspect role, binding, model, provider, budget, and publication restrictions. See IDE Integration Troubleshooting for endpoint checks.

Next steps​