Skip to main content

Spend, Budgets, and API Tokens

Verdictan uses two related command families for cost governance and access publication:

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

The two command families must use an authenticated Verdictan API session or VERDICTAN_API_TOKEN.

verdictan spend​

Spend summary​

verdictan spend summary
verdictan spend summary --since 30d --json

Budgets​

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

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

These commands manage scope spend budgets at /v1/budgets. A standalone gateway with an event sink can use available headroom when selecting a priced target. Headroom can be for an organization, team, user, or key. A connected gateway does not load these scope budget records for routing. Use provider budgets, governed token limits, and usage authorization for the connected request path.

Provider budgets​

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

Provider budgets participate in gateway provider-headroom checks. Before you rely on the control, verify that the target has pricing metadata. Test one allowed request. Test the specified exhausted-budget behavior.

API tokens​

verdictan token​

verdictan token governs the API tokens that applications, IDEs, gateways, and integrations use.

Token lifecycle commands​

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

When to use which token operation​

TaskCommand
Create a new bounded tokenverdictan token create
Narrow mutable metadata or bindingsverdictan token update
Create a narrower copy of a token recordverdictan token clone
Emergency revoke with proof metadataverdictan token emergency-revoke
Replace the raw token value while keeping the token recordverdictan token rotate
Verify a token valueverdictan token validate

Workflow notes​

  • After create or update, use verdictan spend budget get --budget-id ... to make sure that the stored ceiling is correct.
  • Do not identify a stored scope budget as connected-gateway enforcement. See Usage Costs and Budgets.
  • If bounded access is necessary, use verdictan token create. This command does not expose upstream provider credentials directly.
  • create, clone, and rotate can show a raw token value one time. Store that value immediately. Keep JSON output out of logs.
  • verdictan token validate reads the raw token from stdin. Pipe it in from a protected source. Do not put it in shell history or process arguments. If you must type it directly, rerun with --force-tty.
  • After verdictan token rotate, update each consumer immediately. Rotation returns a replacement value. Do not send the previous value to consumers.
  • delete and emergency-revoke must include --yes. Emergency revocation also must include a cause. If applicable, add --revoke-active-sessions.

Next steps​