Agent Integration Guide — Salesbooth Developer Docs

How Agent Authentication Works

Salesbooth uses a delegation model for agents. Instead of giving an agent your API key directly, you create a delegation — a scoped, time-limited authorization that the agent uses to act on your behalf.

Your Account
    │
    ├── Delegation → Agent A (scope: deals:write, budget: $5000/day)
    ├── Delegation → Agent B (scope: products:read, customers:read)
    └── Delegation → Agent C (scope: deals:write + agent:negotiate, budget: $50/deal)

Each delegation has:

Scopes — which API operations the agent can perform
Budget limits — maximum spend per deal or per day
Trust level — determines what actions require human approval
Expiry — delegations auto-expire for security

How agent auth works: API key + delegation ID

An agent authenticates with its own sb_test_* or sb_live_* API key and passes an X-Delegation-ID header to operate within the delegated scope. If an agent is compromised, revoke its delegation without affecting your account or other agents.

Creating Delegations

Create delegations from Settings → Delegations or via the API:

# Create a delegation for an AI agent
curl -X POST https://api.salesbooth.com/v1/delegations \
  -H "Authorization: Bearer $SB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "grantee_agent_key_id": "key_a1b2c3d4e5f6",
    "allowed_actions": ["deals:write", "customers:write", "agent:negotiate"],
    "max_transaction_amount": 500.00,
    "max_daily_amount": 5000.00,
    "expires_at": "2026-12-31T23:59:59Z",
    "description": "Handles inbound leads automatically"
  }'

# Response
{
  "error": false,
  "data": {
    "delegation_id": "del_a1b2c3d4e5f6g7h8",
    "tenant_id": "tenant_abc123",
    "grantor_type": "user",
    "grantor_id": "42",
    "grantee_agent_key_id": "key_a1b2c3d4e5f6",
    "description": "Handles inbound leads automatically",
    "allowed_actions": ["deals:write", "customers:write", "agent:negotiate"],
    "max_transaction_amount": "500.00",
    "max_daily_amount": "5000.00",
    "max_monthly_amount": null,
    "spent_today": "0.00",
    "spent_this_month": "0.00",
    "available_today": "5000.00",
    "available_this_month": null,
    "expires_at": "2026-12-31 23:59:59",
    "revoked_at": null,
    "created_at": "2026-03-24 12:00:00"
  }
}

Agent scopes

Scope	What the agent can do
`deals:read`	List and view deals
`deals:write`	Create, update, and progress deals
`deals:sign`	Sign deals on behalf of the principal
`customers:read`	Look up customer records
`customers:write`	Create and update customers
`products:read`	List and retrieve products and pricing
`products:write`	Create, update, and manage products
`contracts:read`	View contract terms
`contracts:write`	Create, update, and sign contracts
`agent:discover`	List tools, discover agents, and use federation discovery
`agent:negotiate`	Propose and respond to negotiation offers
`agent:execute`	Trigger workflow execution
`intelligence:read`	Read deal intelligence data
`intelligence:write`	Write intelligence actions
`delegations:read`	List and view delegations
`delegations:write`	Create and manage delegations
`webhooks:read`	List and view webhooks
`webhooks:write`	Create and manage webhooks
`subscriptions:write`	Manage subscriptions
`workflow:approve`	Approve workflow steps
`audit:read`	View audit trails
`audit:export`	Export audit data
`sandbox:read`	Read sandbox state
`sandbox:write`	Toggle sandbox mode
`billing:read`	Access billing data

Using a delegation credential

The agent authenticates with its own API key and passes the delegation ID to operate within the delegated scope:

# Step 1: Agent creates the deal using its own API key + delegation ID header
curl -X POST https://api.salesbooth.com/v1/deals \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here" \
  -H "X-Delegation-ID: del_a1b2c3d4" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_abc123",
    "title": "Q2 Enterprise Proposal"
  }'

# Step 2: Add line items separately via add_item action
curl -X POST "https://api.salesbooth.com/v1/deals?id=deal_a1b2c3d4&action=add_item" \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here" \
  -H "X-Delegation-ID: del_a1b2c3d4" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_a1b2c3d4",
    "quantity": 10
  }'

Revoking a delegation

curl -X DELETE "https://api.salesbooth.com/v1/delegations?id=del_a1b2c3d4" \
  -H "Authorization: Bearer $SB_API_KEY"

MCP Protocol

The Model Context Protocol (MCP) endpoint lets AI assistants (Claude, GPT-4, etc.) interact with Salesbooth using natural language tool calls — no custom API integration required.

MCP endpoint

https://api.salesbooth.com/v1/mcp

Configuring your AI assistant

// claude_desktop_config.json
{
  "mcpServers": {
    "salesbooth": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-fetch"],
      "env": {
        "MCP_URL": "https://api.salesbooth.com/v1/mcp",
        "MCP_AUTH": "Bearer sb_test_au_your_agent_key_here",
        "MCP_DELEGATION_ID": "del_a1b2c3d4"
      }
    }
  }
}

// OpenAI function calling — fetch MCP tool definitions via JSON-RPC
const rpc = await fetch('https://api.salesbooth.com/v1/mcp', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sb_test_au_your_agent_key_here',
    'X-Delegation-ID': 'del_a1b2c3d4',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ jsonrpc: '2.0', method: 'tools/list', id: 1 })
}).then(r => r.json());

// Map MCP tool format to OpenAI function calling format
// MCP returns: { name, description, inputSchema }
// OpenAI expects: { type: 'function', function: { name, description, parameters } }
const tools = rpc.result.tools.map(t => ({
  type: 'function',
  function: { name: t.name, description: t.description, parameters: t.inputSchema }
}));

// Use in ChatCompletion request
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [...],
  tools,
  tool_choice: 'auto'
});

# List available MCP tools (JSON-RPC tools/list)
curl -X POST https://api.salesbooth.com/v1/mcp \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here" \
  -H "X-Delegation-ID: del_a1b2c3d4" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Execute a tool call (JSON-RPC tools/call)
curl -X POST https://api.salesbooth.com/v1/mcp \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here" \
  -H "X-Delegation-ID: del_a1b2c3d4" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": 2,
    "params": {
      "name": "create_deal",
      "arguments": {
        "customer_id": "cust_abc123",
        "title": "Enterprise Q2 Proposal",
        "currency": "USD"
      }
    }
  }'

Products are added as line items after deal creation using the add_deal_item tool.

Available MCP tools

A selection of commonly-used tools is shown below. The complete list of 190+ tools — including contracts, bookings, payments, and intelligence — is available by calling the tools/list MCP method on your connected server.

Tool name	Description	Required scope
`discover_deals`	List recent deals with filters	`deals:read`
`create_deal`	Create a new deal	`deals:write`
`check_deal_status`	Retrieve deal details	`deals:read`
`transition_deal`	Progress a deal to a new status	`deals:write`
`negotiate_terms`	Submit a counter-offer	`agent:negotiate`
`accept_deal`	Accept current offer	`agent:negotiate`
`list_products`	List available products	`products:read`
`calculate_pricing`	Simulate pricing for a configuration	`products:read`
`get_customer`	Find a customer by ID or email	`customers:read`
`create_customer`	Create a new customer record	`customers:write`
`generate_quote`	Generate a PDF quote	`deals:read`
`workflow_execute`	Execute a planned workflow	`agent:execute`

Workflow Execution

Workflows let you define multi-step automation sequences that agents can trigger. Define workflows in Intelligence → Agent Workflows.

Triggering a workflow via API

# Trigger a workflow
curl -X POST "https://api.salesbooth.com/v1/agent-workflow?id=wf_a1b2c3d4&action=execute" \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here" \
  -H "X-Delegation-ID: del_a1b2c3d4"

# Response
{
  "error": false,
  "data": {
    "id": "wf_a1b2c3d4",
    "status": "running",
    "started_at": "2026-03-18T12:00:00Z"
  }
}

Checking workflow status

curl "https://api.salesbooth.com/v1/agent-workflow?id=wf_a1b2c3d4" \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here" \
  -H "X-Delegation-ID: del_a1b2c3d4"

Approval gates

Workflows can include approval gates — steps that pause and wait for human approval before proceeding. This is how you keep humans in the loop for high-value decisions:

# Workflow with approval gate (defined in dashboard)
{
  "name": "Inbound Lead Handler",
  "steps": [
    { "type": "get_customer",  "input": "{{ input.customer_email }}" },
    { "type": "create_deal",   "input": { "customer_id": "{{ steps.0.result.id }}" } },
    {
      "type": "approval_gate",
      "condition": "deal.total > 10000",
      "approve_label": "Approve large deal",
      "timeout_hours": 24,
      "on_timeout": "reject"
    },
    { "type": "generate_quote", "input": "{{ steps.1.result.id }}" }
  ]
}

Approval notifications

When a workflow reaches an approval gate, the account owner receives an email and in-app notification. Approve or reject from Intelligence → Agent Workflows → Pending Approvals, or via the API calls below.

Responding to approval gates via API

List workflows waiting for approval, then approve or reject them programmatically:

# List workflows waiting for approval
curl "https://api.salesbooth.com/v1/agent-workflow?action=pending_approvals" \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here" \
  -H "X-Delegation-ID: del_a1b2c3d4"

# Approve a workflow at an approval gate
curl -X POST "https://api.salesbooth.com/v1/agent-workflow?id=wf_a1b2c3d4&action=approve" \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here" \
  -H "X-Delegation-ID: del_a1b2c3d4" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Approved after budget review" }'

# Reject a workflow at an approval gate
curl -X POST "https://api.salesbooth.com/v1/agent-workflow?id=wf_a1b2c3d4&action=reject" \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here" \
  -H "X-Delegation-ID: del_a1b2c3d4" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Deal value exceeds quarterly budget" }'

If the approval email notification needs to be resent, or the request requires escalation to the delegation grantor:

# Resend the approval notification
curl -X POST "https://api.salesbooth.com/v1/agent-workflow?id=wf_a1b2c3d4&action=resend_approval" \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here" \
  -H "X-Delegation-ID: del_a1b2c3d4"

# Escalate to the delegation grantor
curl -X POST "https://api.salesbooth.com/v1/agent-workflow?id=wf_a1b2c3d4&action=escalate_approval" \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here" \
  -H "X-Delegation-ID: del_a1b2c3d4" \
  -H "Content-Type: application/json" \
  -d '{ "escalation_reason": "Reviewer has not responded within 12 hours" }'

Trust Level Progression

The Salesbooth trust system progressively grants agents more autonomy as they demonstrate reliable behavior. Trust is earned, not granted.

0

Untrusted

Discover and read-only access only

1

Provisional

Discover + negotiate; $500 cap per transaction

2

Established

Discover + negotiate + execute; $5,000 cap

3

Trusted

Full capabilities, no per-trust transaction caps

4

Verified Partner

Full capabilities + higher rate limits + priority support

How trust is earned

Completing deals successfully (no disputes or chargebacks)
Staying within budget limits consistently
Maintaining low error rates on API calls
Monthly activity scoring (deal volume + quality)
Deal completion rewards boost score faster

Checking an agent's trust level

curl https://api.salesbooth.com/v1/agent-trust \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here" \
  -H "X-Delegation-ID: del_a1b2c3d4"

{
  "error": false,
  "data": {
    "key_id": "key_abc123",
    "trust_level": 2,
    "trust_label": "Established",
    "trust_score": 847,
    "transaction_cap": 5000.00,
    "capabilities": {
      "discover":            { "unlocked": true,  "required_level": 0, "required_label": "Untrusted" },
      "negotiate":           { "unlocked": true,  "required_level": 1, "required_label": "Provisional" },
      "execute":             { "unlocked": true,  "required_level": 2, "required_label": "Established" },
      "autonomous_workflow": { "unlocked": true,  "required_level": 2, "required_label": "Established" },
      "high_value_deals":    { "unlocked": false, "required_level": 3, "required_label": "Trusted" },
      "bulk_operations":     { "unlocked": false, "required_level": 3, "required_label": "Trusted" },
      "priority_support":    { "unlocked": false, "required_level": 4, "required_label": "Verified Partner" }
    },
    "progress": {
      "next_level": 3,
      "next_label": "Trusted",
      "score_required": 1000,
      "score_current": 847,
      "score_percent": 84.7,
      "deals_required": 10,
      "days_required": 30,
      "max_failures_allowed": 2
    }
  }
}

Trust decay

Trust scores decay over time for inactive agents. An agent that hasn't made any successful deals in 60 days will see its score reduced by 10% per week. Keep agents active or explicitly lock their trust level from the dashboard.

Start agents at trust level 0

New integrations should always start at trust level 0 (probationary). This lets you verify the agent behaves as expected before granting autonomy. Manually promote to level 1+ after reviewing its first few actions.

Budget Limits

Every delegation can have spend limits to prevent runaway agent spending.

# Delegation with budget limits
{
  "grantee_agent_key_id": "key_abc123",
  "allowed_actions": ["deals:write"],
  "max_transaction_amount": 1000.00,   // Max value of any single deal
  "max_daily_amount": 10000.00         // Max daily spend across all deals
}

# Check tenant-level budget (session auth required)
curl https://api.salesbooth.com/v1/budget \
  -H "Cookie: session=..."

{
  "error": false,
  "success": true,
  "data": {
    "budget": {
      "monthly_limit": 5000.00,
      "monthly_limit_cents": 500000,
      "alert_at_percent": [80, 100],
      "current_spend": 2500.00,
      "current_spend_cents": 250000,
      "percent_used": 50.0
    }
  }
}

To check an individual agent's spending limits and usage, retrieve the delegation object:

GET /api/v1/delegations?id={delegation_id}

Budget exceeded behavior

When an agent attempts a deal that would exceed its budget, the API returns:

HTTP 403 Forbidden
{
  "error": true,
  "code": "DELEGATION_BUDGET_EXCEEDED",
  "category": "authorization_error",
  "message": "Deal total $1,500 exceeds per-deal budget limit of $1,000",
  "recovery": {
    "action": "request_approval",
    "approval_url": "https://salesbooth.com/settings/delegations/del_a1b2c3d4/approve"
  }
}

Set conservative budgets initially

Start with tight budget limits and expand as you gain confidence in your agent's behavior. A budget-exceeded error is much easier to handle than an unexpected charge.

Next Steps

Quickstart Guide →

Zero to first deal in 5 minutes

Webhook Integration →

Receive deal events server-side

API Reference →

Full agent API documentation