---
title: API での Session
description: バックエンドで Session を作成し、ブラウザーに渡します。
---

コンソールは Core API のクライアントの 1 つにすぎず、皆さんのプロダクトも同じように Core API を使えます。よくある構成では、役割を次の 2 つに分けます:

- **バックエンド** は [API key](/ja/console/api-keys) を持ち、ユーザーごとに Session を作成します。API key はバックエンドの外に出しません。
- **ブラウザー** のページは Session の **Session token** を受け取り、その Session の中の操作をすべて行います。メッセージの送信、Run の追跡、承認やフォームへの回答、[ページ独自の Tool](/ja/build/client-tools) の提供などです。

いずれも `https://api.us.cloud.subako.ai/v1` への普通の HTTP リクエストで、[SDK](/ja/build/sdks) はこれをラップしたものです。

## Session を作成する

```bash
curl -X POST https://api.us.cloud.subako.ai/v1/sessions \
  -H "Authorization: Bearer $SUBAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-4192-session" \
  -d '{
    "agent_id": "<agent-id>",
    "display_name": "ticket-4192",
    "vault_ids": ["<vault-id>"],
    "metadata": { "tenant_id": "t_123" }
  }'
```

| フィールド | |
| --- | --- |
| `agent_id` | 必須。Session は作成時点での Agent の最新バージョンで実行され、以後もそのバージョンを使い続けます。 |
| `display_name` | 任意。200 文字まで。空の場合、Session に名前を付けることを許可された Agent が名前を付けます。 |
| `vault_ids` | 任意。10 個まで。Session の Tool が Credential を利用できる [Vault](/ja/console/vaults) を指定します。 |
| `metadata` | 任意。英小文字、数字、`_` からなるキーを 50 個まで指定でき、値は 500 文字までの文字列です。作成時に確定し、Session が記録するすべての使用量にコピーされるので、使用量を自社のテナントや顧客ごとに集計できます。Session を削除しても使用量には残るため、ここにはそれ自体に意味を持たない ID を入れ、個人情報は決して入れないでください。 |

API key には **Session** › **作成** の権限が必要です。レスポンスとして、最初の Session token を含む Session が返ります:

```json
{
  "id": "01a0877f-d3b3-7e73-9eed-a16caee8cff7",
  "workspace_id": "01a0877c-03d9-7823-b997-f42147b8b607",
  "agent_id": "01a0877d-9a1f-7c40-8e2b-5b3c4d6e7f80",
  "agent_version_id": "01a0877e-1b2c-7d3e-9f40-a1b2c3d4e5f6",
  "display_name": "ticket-4192",
  "status": "idle",
  "session_token": "sbk_st_...",
  "session_token_expires_at": "2026-09-09T19:48:16Z",
  "metadata": { "tenant_id": "t_123" },
  "created_at": "2026-09-09T18:48:16Z"
}
```

同じ `Idempotency-Key` で再度送ると、Session は新たに作成されず、同じ Session が返ります。ただし、Session token は一度しか表示されないため、このレスポンスには含まれません。必要なら新しい Session token を発行してください。

## Session token

**Session token** (`sbk_st_…`) は、それ自体には権限を持ちません。使えるのは 1 つの Session、つまり `/v1/sessions/{その ID}/` 以下のルートだけです。Session の一覧取得や作成はできず、その Session の外にあるものは何も読めません。

| | API key | Session token |
| --- | --- | --- |
| 範囲 | 1 つの Workspace | 1 つの Session |
| できること | 発行時に与えられた権限 | その Session の中のすべて |
| 置き場所 | サーバー | ブラウザー、またはワーカー |
| 有効期限 | 無効化されたとき、または有効期限 | 発行から 1 時間 |

Session token でできるのは、その Session の中での次の操作です。ログの読み取りと追跡、メッセージの送信、取り消し、承認の許可と拒否、フォームへの回答、Client の登録、Session の名前変更と削除、Volume の読み書き。

Session token の有効期限は 1 時間です。期限が切れる前に、バックエンドから次の Session token を発行してください:

```bash
curl -X POST https://api.us.cloud.subako.ai/v1/sessions/$SESSION_ID/tokens \
  -H "Authorization: Bearer $SUBAKO_API_KEY"
```

これには **Session** › **管理** の権限が必要です。Session token で Session token を発行することはできません。

## Session とやり取りする

```bash
# メッセージを送ります。Run を開始するか、実行中の Run に指示します。
curl -X POST https://api.us.cloud.subako.ai/v1/sessions/$SESSION_ID/events \
  -H "Authorization: Bearer $SUBAKO_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "input", "text": "Summarize ticket 4192."}'
# {"run_id": "01a08780-...", "outcome": "new_run"}

# 実行中の Run を停止します。
curl -X POST https://api.us.cloud.subako.ai/v1/sessions/$SESSION_ID/cancel \
  -H "Authorization: Bearer $SUBAKO_SESSION_TOKEN"
```

Run の実行中に入力を送ると `"outcome": "steered"` が返り、その入力は Run の終了を待たずに実行中の Run に加わります。取り消しは協調的に行われ、Run は次のチェックポイントで止まって `run_cancelled` で終わります。

Session で起きていることは [Event のストリーム](/ja/build/streaming-events) で追えます。

## ブラウザーから呼び出す

ページは Session token で API を呼び出します。その際ブラウザーは、ページの Origin からの呼び出しが許可されているかを事前に確認します。これが **CORS** です。許可する Origin は Agent ごとに、コンソールの Agent のページ (**CORS** › **編集**)、`subako agent set-security`、または API で設定します:

```bash
curl -X PUT https://api.us.cloud.subako.ai/v1/agents/$AGENT_ID/security \
  -H "Authorization: Bearer $SUBAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allowed_origins": ["https://app.acme.example"]}'
```

Origin は `scheme://host[:port]` の形式で書き、パスは含めません。`*` を指定するとすべての Origin を許可します。この設定が適用されるのは、その Agent の Session の `/v1/sessions/{id}/` 以下のルートだけです。ページから Session を作成したり API key を使ったりすることはできないので、API key はサーバーの外に出ません。

ブラウザーの `EventSource` は `Authorization` Header を送れないため、ストリームは `fetch` で読んでください。TypeScript SDK もこの方法で読んでいます。

## 一覧の取得と後片付け

```bash
curl "https://api.us.cloud.subako.ai/v1/sessions?agent_id=$AGENT_ID&limit=20" \
  -H "Authorization: Bearer $SUBAKO_API_KEY"

curl -X DELETE https://api.us.cloud.subako.ai/v1/sessions/$SESSION_ID \
  -H "Authorization: Bearer $SUBAKO_API_KEY"
```

Session を削除すると、そのログと Volume も削除されます。記録済みの使用量は削除されずに残ります。

認証、Workspace の Header、ページネーション、エラー、冪等性については [API の規約](/ja/reference/api) を参照してください。