manage-subaccounts

Bolna 子账户

企业功能：将一个父组织拆分为相互隔离的子账户工作区。每个子账户都有自己的自动配置 API 密钥（以 sa- 为前缀）、自己的智能体、电话号码、批次、执行记录，以及单独的用量流；这些用量会汇总到父账户以便计费。

仅限企业版。 如果 POST /sub-accounts/create 返回 403，说明该账户不属于企业版。请联系 [email protected]。

适用场景

原因	示例
多租户（代理商 / 经销商）	每个代理商对应一个 Bolna 组织；每个客户对应一个子账户。
部门隔离	销售 / 支持 / 市场部门共用一个组织，但需要独立的工作区。
区域 / 合规边界	欧盟客户数据存放在标记为欧盟的子账户中。
环境	在一个计费主体下设置开发 / 预发布 / 生产子账户。

子账户提供的功能

• 数据隔离：智能体、通话、电话号码、批次和执行记录不会在不同子账户之间混杂。
• 自动配置 API 密钥：创建子账户时同时生成，前缀为 sa-。
• 每个子账户独立用量：提供单独的 /usage 端点，用于计费核对。
• 集中计费：所有子账户的费用都会计入父账户钱包。
• 仅限父账户控制：子账户不能创建或删除自己的子账户，也不能修改其他子账户。

端点

方法	路径	用途
POST	/sub-accounts/create	创建新的子账户
GET	/sub-accounts/all	列出所有子账户
PATCH	/sub-accounts/{sub_account_id}	更新名称 / 元数据
DELETE	/sub-accounts/{sub_account_id}	删除（级联删除所有子账户数据）
GET	/sub-accounts/{sub_account_id}/usage	获取单个子账户的用量
GET	/sub-accounts/all/usage	获取所有子账户的用量汇总

身份验证：使用父账户的 Authorization: Bearer $BOLNA_API_KEY（父组织的管理员密钥）。

创建

curl -X POST https://api.bolna.ai/sub-accounts/create \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Client - Customer A",
    "description": "Customer A workspace under Acme agency",
    "metadata": {
      "customer_id": "cust_abc123",
      "region": "in",
      "environment": "production"
    }
  }'

响应中包含：

{
  "id": "subacct_01HQXYZ123",
  "name": "Acme Client - Customer A",
  "api_key": "sa-bna_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "created_at": "2026-05-19T10:00:00Z"
}

api_key 只会显示一次。 请立即保存。子账户不能自行重新生成密钥——只有父账户可以。

使用子账户密钥

子账户 API 密钥的工作方式与顶层密钥完全相同，但只能操作子账户的资源：

export SA_KEY="sa-bna_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Creates an agent inside the sub-account
curl -X POST https://api.bolna.ai/v2/agent \
  -H "Authorization: Bearer $SA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_config": {...}, "agent_prompts": {...} }'

任何需要区分父账户与子账户行为的代码，都可以根据 sa- 前缀进行判断。

列出子账户

curl https://api.bolna.ai/sub-accounts/all \
  -H "Authorization: Bearer $BOLNA_API_KEY"

支持分页。使用 page_number / page_size 查询参数（参见 https://raw.githubusercontent.com/bolna-ai/skills/main/references/bolna-core.md）。

查看用量

单个子账户：

curl "https://api.bolna.ai/sub-accounts/$SUB_ACCOUNT_ID/usage" \
  -H "Authorization: Bearer $BOLNA_API_KEY"

所有子账户：

curl https://api.bolna.ai/sub-accounts/all/usage \
  -H "Authorization: Bearer $BOLNA_API_KEY"

用量数据通常包括通话分钟数、执行次数、电话号码租用情况和费用，可用于计费核对。可按周或按日拉取，并存储在自己的数据仓库中。

修改

curl -X PATCH "https://api.bolna.ai/sub-accounts/$SUB_ACCOUNT_ID" \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Client - Customer A (Renamed)" }'

修改时不会重新生成 API 密钥。要轮换密钥，请删除并重新创建子账户。

删除——请谨慎操作

curl -X DELETE "https://api.bolna.ai/sub-accounts/$SUB_ACCOUNT_ID" \
  -H "Authorization: Bearer $BOLNA_API_KEY"

删除操作会级联删除：

• 子账户中的所有智能体。
• 所有批次、执行记录和录音。
• 子账户拥有的所有电话号码（释放 DID；这些号码将无法再使用）。
• 所有配置和 sa- API 密钥。

删除前务必与用户确认。可提供备份选项：

• 智能体配置：对每个智能体调用 GET /v2/agent/{id}。
• 执行数据：分页调用 GET /v2/agent/{id}/executions。
• 处置定义：调用 GET /dispositions/?agent_id=...。

对于有审计要求的组织，请在发出 DELETE 请求之前将这些数据归档到自己的存储中。

常见模式

按客户划分工作区（代理商模式）

def onboard_new_client(client_name, client_id):
    sub = create_sub_account(name=f"Client - {client_name}", metadata={"client_id": client_id})
    store_in_db(client_id=client_id, sub_account_id=sub["id"], api_key=sub["api_key"])
    bootstrap_agents_for_client(sub["api_key"])

环境隔离

创建三个子账户：acme-dev、acme-staging、acme-production。在各个环境中使用对应的 sa- 密钥。日志、通话和电话号码都会正确标记，无需手动筛选。

租户计费核对

定时任务每周拉取 GET /sub-accounts/all/usage，将各子账户的用量与 clients 表关联，并生成发票。

注意事项

• 子账户无法创建自己的子账户。 只有父组织管理员可以创建。
• sa- 密钥无法访问其他子账户。 严格隔离。
• 钱包归父级所有。 子账户没有单独的钱包，需为父级充值。
• 并发限制可能由多个子账户共享，也可能按子账户分别计算，具体取决于套餐；请查看 GET /sub-accounts/{id}/usage 获取限制信息。
• 通过子账户购买的电话号码归该子账户所有。 删除子账户时会释放这些号码。

深入了解

文件	内容
scripts/create_sub_account.py	使用名称和元数据标志封装 POST /sub-accounts/create。
scripts/list_sub_accounts.py	使用分页封装 GET /sub-accounts/all。
scripts/sub_account_usage.py	封装 GET /sub-accounts/{id}/usage 和所有账户的用量汇总。

另请参阅

• setup-api-key — 密钥以及 sa- 前缀的区别。
• https://raw.githubusercontent.com/bolna-ai/skills/main/references/bolna-core.md — 身份验证、分页。
• Bolna Enterprise：访问 https://www.bolna.ai/meet 升级套餐。