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

Agent credentials are separate from API keys

Agents receive signed credentials, not your API key. 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://salesbooth.com/api/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

# Agent uses the credential token as Bearer auth
curl -X POST https://salesbooth.com/api/v1/deals \
  -H "Authorization: Bearer sbagent_eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_abc123",
    "title": "Q2 Enterprise Proposal",
    "products": [{"id": "prod_a1b2c3d4", "quantity": 10}]
  }'

Revoking a delegation

curl -X DELETE "https://salesbooth.com/api/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://salesbooth.com/api/v1/mcp

Configuring your AI assistant

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

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

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

# List available MCP tools (JSON-RPC tools/list)
curl -X POST https://salesbooth.com/api/v1/mcp \
  -H "Authorization: Bearer sbagent_eyJhbGci..." \
  -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://salesbooth.com/api/v1/mcp \
  -H "Authorization: Bearer sbagent_eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": 2,
    "params": {
      "name": "create_deal",
      "arguments": {
        "customer_email": "buyer@example.com",
        "product_ids": ["prod_a1b2c3d4"],
        "title": "Enterprise Q2 Proposal"
      }
    }
  }'

Available MCP tools

Tool name	Description	Required scope
`list_deals`	List recent deals with filters	`deals:read`
`create_deal`	Create a new deal	`deals:write`
`get_deal`	Retrieve deal details	`deals:read`
`update_deal_status`	Progress a deal to a new status	`deals:write`
`propose_negotiation`	Submit a counter-offer	`agent:negotiate`
`accept_negotiation`	Accept current offer	`agent:negotiate`
`list_products`	List available products	`products:read`
`get_pricing`	Simulate pricing for a configuration	`products:read`
`lookup_customer`	Find a customer by email	`customers:read`
`create_customer`	Create a new customer record	`customers:write`
`generate_quote`	Generate a PDF quote	`deals:read`
`execute_workflow`	Trigger a 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://salesbooth.com/api/v1/agent-workflow?id=wf_a1b2c3d4&action=execute" \
  -H "Authorization: Bearer sbagent_eyJhbGci..."

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

Checking workflow status

curl "https://salesbooth.com/api/v1/agent-workflow?id=wf_a1b2c3d4" \
  -H "Authorization: Bearer sbagent_eyJhbGci..."

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": "lookup_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": "send_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.

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://salesbooth.com/api/v1/agent-trust \
  -H "Authorization: Bearer sbagent_eyJhbGci..."

{
  "error": false,
  "data": {
    "key_id": "key_abc123",
    "trust_level": 2,
    "trust_label": "Verified",
    "trust_score": 847,
    "transaction_cap": 10000.00,
    "capabilities": {
      "create_deal": { "unlocked": true, "required_level": 0, "required_label": "Probationary" },
      "apply_discount": { "unlocked": true, "required_level": 1, "required_label": "Trusted" },
      "issue_refund": { "unlocked": false, "required_level": 3, "required_label": "Established" }
    },
    "progress": {
      "next_level": 3,
      "next_label": "Established",
      "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://salesbooth.com/api/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