Skip to main content

Spend, Budgets, and API Tokens

Keeptrusts splits cost governance and access publishing across two adjacent command families:

  • kt spend handles reporting, budgets, and provider budgets.
  • kt token handles governed API token lifecycle.

Both command families require an authenticated Keeptrusts API session or KEEPTRUSTS_API_TOKEN.

kt spend​

Spend summary​

kt spend summary
kt spend summary --since 30d --json

Budgets​

Budgets require --name, --max-budget, and --target-type. Use --target-id for key, user, or team targets.

kt spend budget list
kt spend budget get --budget-id budget_abc123
kt spend budget create --name "Monthly Cap" --max-budget 10000 --target-type organization --reset-schedule monthly
kt spend budget update --budget-id budget_abc123 --max-budget 15000
kt spend budget delete --budget-id budget_abc123 --yes

These commands manage scope spend budgets under /v1/budgets. A standalone gateway with an event sink can use the remaining organization, team, user, or key headroom when selecting a priced target. A connected gateway does not load these scope budget records for routing; use provider budgets, governed token limits, and wallet state for the connected request path.

Provider budgets​

kt spend provider-budget list
kt spend provider-budget get --budget-id pb_abc123
kt spend provider-budget create --provider openai --limit-usd 5000 --period monthly
kt spend provider-budget delete --budget-id pb_abc123 --yes

Provider budgets participate in gateway provider-headroom checks. Verify that the target has pricing metadata and exercise both an allowed request and the expected exhausted-budget behavior before relying on the control.

API Tokens​

kt token​

kt token governs the customer-facing API tokens that applications, IDEs, gateways, and integrations use.

Common lifecycle commands​

kt token list
kt token list --purpose gateway-runtime
kt token get tok_abc123
kt token create --name ci-bot --purpose gateway-runtime --key-class disposable --max-budget 25 --max-requests 500 --expires-in 24h
kt token update tok_abc123 --team-id team_abc123
kt token clone tok_abc123 --reason incident-response --model-filter your-model-id
kt token rotate tok_abc123
kt token validate kt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
kt token delete tok_abc123 --yes
kt token emergency-revoke tok_abc123 --reason "suspected credential exposure" --yes

When to use which token operation​

NeedCommand
Create a new bounded tokenkt token create
Narrow mutable metadata or bindingskt token update
Produce a narrower copy of an existing tokenkt token clone
Emergency revoke with proof metadatakt token emergency-revoke
Replace the raw token value while keeping the token recordkt token rotate
Check whether a token value is still validkt token validate

Workflow notes​

  • Use kt spend budget get --budget-id ... after create or update to confirm the stored ceiling.
  • Do not describe a stored scope budget as connected-gateway enforcement; see Spend, Budgets, and Billing.
  • Use kt token create when you need bounded access without exposing upstream provider credentials directly.
  • create, clone, and rotate can reveal a raw token value once. Store that value immediately and keep JSON output out of logs.
  • kt token validate requires the raw token as a positional argument, which can expose it in shell history or process inspection. Run it only in a controlled shell and clear any retained history.
  • After kt token rotate, update every consumer immediately. Rotation returns a replacement value and the previous value is no longer the credential to distribute.
  • delete and emergency-revoke require --yes. Emergency revocation also requires a reason and can add --revoke-active-sessions when applicable.

Next steps​