Quickstart

API base: https://api.callvault.dev. Hero route: POST /v1/tools/execute. Control keys use bk_test_* or bk_live_* prefixes only (server env — never in agents).

Your server mints broker JWTs; your agent executes tools; your operator connects SaaS accounts in the dashboard.

1. Operator: connect GitHub

Sign in at https://app.callvault.dev, open Connections, and complete GitHub OAuth. You receive a connected_account_id handle — not raw tokens.

2. Server: mint a broker JWT

Store a control API key (bk_test_* or bk_live_*) in server environment only. Use BrokerControlClient from @broker/sdk-ts:

import { BrokerControlClient } from "@broker/sdk-ts";

const control = new BrokerControlClient({
  baseUrl: "https://api.callvault.dev",
  controlApiKey: process.env.BROKER_CONTROL_API_KEY!,
});

const { access_token } = await control.mintBrokerToken({
  agent_app_id: process.env.AGENT_APP_ID!,
  env: "test", // or "live"
});

Pass access_token to the agent process. Never pass the control key.

3. Agent: execute a tool

import { BrokerAgentClient } from "@broker/sdk-ts";

const agent = new BrokerAgentClient({
  baseUrl: "https://api.callvault.dev",
  accessToken: brokerJwtFromYourServer,
});

const { invocation_id, result } = await agent.executeTool({
  tool_name: "github.get_authenticated_user",
  connected_account_id: process.env.CONNECTION_ID!,
  arguments: {},
});

High-risk tools may return 409 approval_required. Surface the invocation to an operator in the dashboard, then call continueInvocation or re-execute with an approval id.

4. curl (smoke test)

export FULL_KEY="bk_test_..."
export BROKER_JWT="$(curl -s -X POST https://api.callvault.dev/v1/broker/token \
  -H "Authorization: Bearer $FULL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_app_id":"<uuid>","env":"test"}' | jq -r .access_token)"

curl -s -X POST https://api.callvault.dev/v1/tools/execute \
  -H "Authorization: Bearer $BROKER_JWT" \
  -H "Content-Type: application/json" \
  -d '{"tool_name":"github.get_authenticated_user","connected_account_id":"<uuid>","arguments":{}}'