api-sandbox 0.1.2

CLI for API sandboxes. Test your APIs in a sandbox env.

api-sandbox

api-sandbox installs the sdb CLI.

Use it to:

• publish an API into a sandbox from an OpenAPI spec
• consume a sandboxed API with issued credentials and bearer login
• inspect traces and exercise customer-facing simulation behavior

Publisher + consumer only. No DAC operator workflows here.

Install

Recommended:

pipx install api-sandbox

Upgrade:

pipx upgrade api-sandbox

If you already manage your own virtualenv:

python -m pip install api-sandbox

Requirements:

• Python 3.12+
• pipx recommended

Verify:

sdb --help
sdb doctor --json

Configure A Profile

Hosted sandbox setup:

export API_SANDBOX_TOKEN=replace-me

sdb config init customer \
  --base-url https://control-plane.example.com \
  --runtime-base-url https://runtime.example.com \
  --control-plane-token-env API_SANDBOX_TOKEN \
  --activate

sdb doctor --json

The control-plane token stays outside config JSON.

Publisher Flow

Import a spec:

sdb spec import ./openapi.yaml

Create a sandbox:

sdb sandbox create bank-sim --api "Payments API" --mode mock

Create release inputs:

sdb auth create-profile payments-sim \
  --mode simulated \
  --scheme ApiKeyAuth=api_key \
  --scheme BearerAuth=bearer

sdb policy create scope-only

Create the release with exact names:

sdb release create bank-sim \
  --spec "Payments API@2026-04-14" \
  --auth-profile payments-sim \
  --policy-pack scope-only

List the release, then promote:

sdb release list --sandbox bank-sim
sdb release promote bank-sim --alias latest --release <RELEASE_ID>

Consumer Flow

Create an application:

sdb auth create-app bank-sim partner-app \
  --alias latest \
  --auth-profile payments-sim \
  --scheme BearerAuth

Issue client credentials by app name:

sdb auth issue-client partner-app --sandbox bank-sim --scope refunds.read

Discover auth:

sdb auth discover bank-sim --alias latest
sdb auth scopes bank-sim --alias latest

Login once:

printf '%s\n' "<CLIENT_SECRET>" | sdb auth login bank-sim \
  --alias latest \
  --client-id <CLIENT_ID> \
  --client-secret-stdin \
  --scope refunds.read

auth login saves a local bearer session by default.

Call the runtime without re-threading the bearer token:

sdb sandbox request bank-sim GET /refunds/ref_123 --alias latest

Inspect traces:

sdb trace tail bank-sim --limit 10
sdb trace list --sandbox bank-sim

Simulation

Create a customer simulation pack:

sdb simulation create-pack retail-banking-sim \
  --kind scenario_v1 \
  --seed 'getAccount@{"account_id":"{account_id}","balance":100}' \
  --scenario '{"scenario_id":"credit-ladder","name":"Credit ladder","state_patches":[{"path":"/accounts/{account_id}","body":{"status":"credited"}}]}'

List packs or attach one to a release by name:

sdb simulation list-packs --limit 10
sdb release create bank-sim \
  --spec "Payments API@2026-04-14" \
  --simulation-pack retail-banking-sim

End-User Docs

• Install + setup: Public CLI install
• Publisher journey: Publisher runbook
• Consumer journey: Consumer runbook
• Simulation journey: Simulation runbook
• Troubleshooting: Troubleshooting
• CLI contract: CLI contract

What Works

• spec import, validate, diff, list, get
• sandbox create, list, get, clone, archive, export-manifest, reset
• release create, list, get, promote
• auth profiles, apps, client credentials, discovery, scopes, login
• exact-name selectors on hot refs: spec, sandbox, auth profile, app, policy pack, simulation pack
• saved bearer sessions reused by sdb sandbox request
• customer simulation packs, scenarios, snapshots, timers, webhooks, events
• trace list, get, replay, tail
• --dry-run, --yes, --watch, --trace

Homepage: digitalapi.ai