manage-subaccounts

Bolna サブアカウント

エンタープライズ向け機能です。親組織を、互いに分離されたサブアカウントのワークスペースに分割します。各サブアカウントには、個別に自動プロビジョニングされる API キー（sa- がプレフィックス）、独自のエージェント、電話番号、バッチ、実行が用意されます。また、個別の使用状況データが親アカウントに集約され、請求に反映されます。

エンタープライズプラン限定です。 POST /sub-accounts/create が 403 を返す場合、そのアカウントはエンタープライズプランではありません。[email protected] にお問い合わせください。

使用する場面

理由	例
マルチテナント（代理店／再販業者）	Bolna 組織を代理店ごとに 1 つ作成し、クライアントごとにサブアカウントを 1 つ作成します。
部門ごとの分離	営業／サポート／マーケティングで組織を共有しつつ、個別のワークスペースを使用します。
地域／コンプライアンス上の境界	EU の顧客データを EU のタグが付いたサブアカウントに保存します。
環境	1 つの請求アカウントのもとで、開発／ステージング／本番環境用のサブアカウントを作成します。

サブアカウントで利用できる機能

• データの分離：エージェント、通話、電話番号、バッチ、実行がサブアカウント間で混在しません。
• 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	1 つのサブアカウントの使用状況を取得します
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"])

環境の分離

3 つのサブアカウント（acme-dev、acme-staging、acme-production）を作成します。各環境で対応する sa- キーを使用します。ログ、通話、電話番号に正しいタグが付くため、手動でフィルタリングする必要はありません。

テナントの請求内容の照合

Cron ジョブで 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 をご覧ください。