WireCanal API リファレンス

API キーひとつで、canal の作成から一覧・更新・削除・アクセスログ取得まで。ダッシュボード（WebUI）とほぼ同等の操作を、プログラムから実行できます。

概要と対応プラン

ダッシュボード（WebUI）でできる canal 操作を、API キー認証の REST API でほぼすべて実行できます。応答はすべて JSON です。

canal の作成／一覧／詳細／更新（転送先・アクセス保護）／削除
公開の一時停止／再開・アクセスログの取得
wirecanal.json（Agent 設定）の取得（単体・複数まとめ）・まとめ運用の組の記録
自分の枠（プラン・上限・使用数）とエッジ（シャード）一覧の確認

workspace_premiumプレミアムプラン以上でご利用いただけます

公開 API（api_access）はプレミアム以上のプランの機能です。プラン検査は API キーの発行時と使用時の両方で行われます。

認証

認証は API キー（wk_で始まる 35 文字）による Bearer 認証です。キーはダッシュボードの/api-keysで発行し（プレミアム以上・上限 10 個/ユーザー）、発行直後に 1 回だけ表示されます。サーバーは sha256 ハッシュのみを保存するため、万一ダンプが漏れても実キーは復元できません（紛失時は失効 → 再発行）。権限はcanal:rw（自分の canal の読み書き）の 1 種類です。

Authorization: Bearer wk_（あなたのキー）

shieldCookie・CSRF トークンは不要（使いません）

Bearer のみの認証なので CSRF は原理的に成立せず、CORS ヘッダも出しません（ブラウザからの誤用防止）。全操作は所有者スコープで、他人の canal は存在ごと 404（存在有無も開示しません）。

各キーには用途メモ（最大 2000 文字）を付けられます。CI 用・検証用など複数キーの使い分けも、一覧を見れば分かります。

レート制限

レート制限は読み取り 60 回/分・書き込み 20 回/分（ユーザー単位）です。超過すると429＋Retry-After（秒）を返します。しばらく待ってから再試行してください。

エンドポイント

ベース URL はhttps://app.wirecanal.com/v1/api。応答は常に JSON で、エラーは{"error": "<コード>"}形式です。以下のサンプルは、KEYに発行した API キーを入れて実行してください。

KEY="wk_（あなたのキー）"

枠の確認

GET/v1/api/me

プラン・canal の上限・使用数と、使用中の API キー名を返します。

curl -sS -H "Authorization: Bearer $KEY" \
     https://app.wirecanal.com/v1/api/me

{
  "uid": "...",
  "plan_key": "premium",
  "max_canals": 20,
  "used_canals": 3,
  "api_key_name": "ci-bot"
}

エッジ一覧

GET/v1/api/shards

canal 作成時に指定できる収容エッジ（シャード）の候補一覧です。

curl -sS -H "Authorization: Bearer $KEY" \
     https://app.wirecanal.com/v1/api/shards

{
  "shards": [
    {"shard_id": "ja000"},
    {"shard_id": "ja001"},
    {"shard_id": "ja100"},
    {"shard_id": "ja200"},
    {"shard_id": "jan000"}
  ]
}

canal 一覧

GET/v1/api/canals

自分が保有するすべての canal を返します（各要素は「canal 詳細」と同じ canal 表現）。

curl -sS -H "Authorization: Bearer $KEY" \
     https://app.wirecanal.com/v1/api/canals

{
  "canals": [ /* canal 表現の配列（下記「canal 詳細」を参照） */ ]
}

canal 作成

POST/v1/api/canals

canal を作成します。応答には canal 表現に加えてagent_json（wirecanal.json の中身）が同梱され、1 往復で配線できます。

パラメータ		型	説明
forward_target	任意	string	転送先（`host:port`。省略時は`localhost:3000`）
type	任意	string	`http`（既定）／`tcp`／`mcp`
subdomain	任意	string	希望サブドメイン（有料プラン）
custom_domain	任意	string	独自ドメイン（プレミアム）
shard	任意	string	収容エッジ（`GET /v1/api/shards`の候補から）
memo	任意	string	用途メモ（最大 2000 文字。ダッシュボードの一覧・詳細にも表示）
param_a / param_b / param_c	任意	string	追加パラメータ（各最大 512 文字）。タグのように任意の属性を保存できる API 専用の置き場（画面には表示されません）

curl -sS -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
     -d '{"forward_target":"localhost:8080"}' \
     https://app.wirecanal.com/v1/api/canals

{
  "canal_id": "...",
  "type": "http",
  "forward_target": "localhost:8080",
  "shard": "ja001",
  "reserved": false,
  "expires_at": null,
  "suspended": false,
  "user_paused": false,
  "agent_group": null,
  "memo": null,
  "param_a": null,
  "param_b": null,
  "param_c": null,
  "response_timeout_sec": null,
  "protection": {
    "ip":       {"enabled": false, "allow": []},
    "basic":    {"enabled": false},
    "bearer":   {"enabled": false, "count": 0},
    "country":  {"enabled": false},
    "schedule": {"enabled": false},
    "path":     {"enabled": false},
    "fail2ban": {"enabled": false},
    "stealth":  {"enabled": false}
  },
  "hostname": "ab12cd34.ja001.wirecanal.com",
  "url": "https://ab12cd34.ja001.wirecanal.com/",
  "agent_json": {"access_key": "ck_...", "forward_target": "localhost:8080"}
}

bolt1 往復で配線完了

応答のagent_jsonをそのままwirecanal.jsonに保存すれば、あとは Agent を起動するだけで公開されます。

canal 詳細

GET/v1/api/canals/{canal_id}

1 件の canal 表現を返します。秘密値（BASIC のユーザー名/パスワード・Bearer トークン実値）は返しません。

curl -sS -H "Authorization: Bearer $KEY" \
     https://app.wirecanal.com/v1/api/canals/{canal_id}

{
  "canal_id": "...",
  "type": "http",
  "forward_target": "localhost:8080",
  "shard": "ja001",
  "reserved": true,
  "expires_at": null,
  "suspended": false,
  "user_paused": false,
  "agent_group": null,
  "memo": "社内売上ダッシュボード用",
  "param_a": "env=prod",
  "param_b": null,
  "param_c": null,
  "protection": { /* 8 セクション（下記「転送先・保護の更新」を参照） */ },
  "hostname": "myapp.ja001.wirecanal.com",
  "url": "https://myapp.ja001.wirecanal.com/"
}

転送先・アクセス保護の更新

PATCH/v1/api/canals/{canal_id}

転送先とアクセス保護を更新します。保護は 8 セクションのセクション単位シャローマージ（書いたセクションだけ差し替え）です。

パラメータ		型	説明
forward_target	任意	string	転送先の変更
protection	任意	object	8 セクション（`ip`／`basic`／`bearer`／`country`／`schedule`／`path`／`fail2ban`／`stealth`）
memo	任意	string	用途メモの更新（最大 2000 文字。`null`か空文字でクリア・未指定は不変）
param_a / param_b / param_c	任意	string	追加パラメータの更新（各最大 512 文字。`null`か空文字でクリア・未指定は不変）
response_timeout_sec	任意	integer	応答待ち時間の上書き（秒・1〜3600・`null`で既定の 120 秒に戻す）。転送先が応答を返し始めるまでの待ち時間で、処理に時間のかかる同期 API を公開する canal だけ延長できます。有償プランのみ（無料プランでの指定は 403`plan_required`）・HTTP / MCP canal のみ（TCP への指定は 400`bad_timeout`）。反映は最大 60 秒

curl -sS -X PATCH -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
     -d '{"protection":{"ip":{"enabled":true,"allow":["203.0.113.0/24"]}}}' \
     https://app.wirecanal.com/v1/api/canals/{canal_id}

応答は更新後の canal 表現です。protectionは常に 8 セクション全部が載ります（秘密値は返しません）:

"protection": {
  "ip":       {"enabled": true, "allow": ["203.0.113.0/24"]},
  "basic":    {"enabled": true},
  "bearer":   {"enabled": true, "count": 2},
  "country":  {"enabled": true, "mode": "allow", "list": ["JP"]},
  "schedule": {"enabled": true, "tz": "Asia/Tokyo", "rules": [{"days": [1, 2, 3, 4, 5], "from": "09:00", "to": "18:00"}]},
  "path":     {"enabled": true, "scanner_block": true, "rules": [{"action": "deny", "pattern": "/admin/*"}]},
  "fail2ban": {"enabled": true},
  "stealth":  {"enabled": true}
}

パス別の追加条件（`path.rules[].require`）

パス制限のallowルールには、そのパスだけの追加条件（接続元 IP の制限・BASIC / Bearer 認証）を付けられます。canal 全体は公開したまま、/admin配下だけ社内 IP と BASIC を要求する、といった構成が API だけで組めます。

curl -sS -X PATCH -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
     -d '{"protection":{"path":{"enabled":true,"rules":[
           {"action":"allow","pattern":"/admin/*","require":{"ip":["203.0.113.0/24"],"basic":{"user":"ops","pass":"<パスワード>"}}},
           {"action":"allow","pattern":"/*"}
         ]}}}' \
     https://app.wirecanal.com/v1/api/canals/{canal_id}

require.ip… そのパスへの接続元を IP / CIDR で限定（canal 全体の IP 制限とは AND）。不一致は 403。
require.basic/require.bearer… そのパスだけ認証を要求。認証条件のあるパスではその認証だけが鍵になります（canal 全体の認証では通れません）。
同じ要素（basic どうし・bearer どうし）を canal 全体とパス別の両方に設定することはできません（400bad_path）。
応答ではrequireの資格情報は返しません（basicは{"enabled": true}・bearerは{"enabled": true, "count": n}・ipは実値）。

よくあるスキャンパスの一括遮断（`path.scanner_block`）

"scanner_block": trueで、インターネットの自動スキャンが定番で叩くパス（/wp-admin・/.env・/.git・/phpmyadminなど約 30 パターン）を常に 404で遮断します。他のどの保護よりも先に判定し、存在情報を与えません。自動ブロック（fail2ban）が有効なら、これらのパスへのアクセスもカウントに乗ります。rulesを空にしてscanner_blockだけ使うこともできます。

rule検証は fail-closed

protection内に 1 セクションでも不正があると、その PATCH の protection 変更は一切保存されません（400・設定は不変）。書いたセクションだけが差し替わり、書かなかったセクションは変わりません。

canal 削除

DELETE/v1/api/canals/{canal_id}

canal を削除します（アクセスログも連動して削除されます）。削除後は公開 URL が即失効します。

curl -sS -X DELETE -H "Authorization: Bearer $KEY" \
     https://app.wirecanal.com/v1/api/canals/{canal_id}

{"success": true}

公開の一時停止

POST/v1/api/canals/{canal_id}/pause

公開を一時停止します（公開側は 404 になります）。応答は更新後の canal 表現で、user_pausedがtrueになります。

curl -sS -X POST -H "Authorization: Bearer $KEY" \
     https://app.wirecanal.com/v1/api/canals/{canal_id}/pause

{
  "canal_id": "...",
  "user_paused": true,
  "...": "他フィールドは canal 表現（canal 詳細）と同形"
}

公開の再開

POST/v1/api/canals/{canal_id}/resume

一時停止を解除します。応答は canal 表現でuser_pausedがfalseになります。運営による停止中は解除できません（403 suspended_by_operator）。

curl -sS -X POST -H "Authorization: Bearer $KEY" \
     https://app.wirecanal.com/v1/api/canals/{canal_id}/resume

{
  "canal_id": "...",
  "user_paused": false,
  "...": "他フィールドは canal 表現（canal 詳細）と同形"
}

wirecanal.json の取得

GET/v1/api/canals/{canal_id}/agent-json

1 件分の Agent 設定（wirecanal.json の中身）を返します。そのままwirecanal.jsonに保存できます。

curl -sS -H "Authorization: Bearer $KEY" \
     https://app.wirecanal.com/v1/api/canals/{canal_id}/agent-json

{"access_key": "ck_...", "forward_target": "localhost:8080"}

smart_toyMCP canal は 4 キー

MCP canal の場合はmodeとtools（{"default":"deny","allow":[]}）が加わった 4 キーで返ります。

複数 canal をまとめて取得

GET/v1/api/agent-json?ids=<id1>,<id2>

1 台のマシンでまとめて動かすための複数形式（{"canals":[...]}）を返します（1〜32 件・1 件でも他人/不明があれば全体 404）。

curl -sS -H "Authorization: Bearer $KEY" \
     "https://app.wirecanal.com/v1/api/agent-json?ids=<id1>,<id2>"

{
  "canals": [
    {"access_key": "ck_...", "forward_target": "localhost:8080"},
    {"access_key": "ck_...", "forward_target": "localhost:3000"}
  ]
}

まとめ運用の組の記録

POST/v1/api/canals/agent-group

まとめ運用の組を記録します（2 件以上＝組を編成・1 件＝解除）。

パラメータ		型	説明
ids	必須	string[]	canal_id の配列（1〜32 件。2 件以上で編成・1 件で解除）

curl -sS -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
     -d '{"ids":["<id1>","<id2>"]}' \
     https://app.wirecanal.com/v1/api/canals/agent-group

{"success": true, "group": "..."}

アクセスログの取得

GET/v1/api/canals/{canal_id}/access-log?offset=0

canal に到達したアクセスを新しい順・100 件/頁で返します。1 行 ={ts, ip, method, path, result, ua, referer}。resultは転送先の応答コードまたは遮断理由です。

パラメータ		型	説明
offset	任意	integer	取得開始位置（既定 0・1 頁 100 件）

curl -sS -H "Authorization: Bearer $KEY" \
     "https://app.wirecanal.com/v1/api/canals/{canal_id}/access-log?offset=0"

{
  "entries": [
    {"ts": 1720000000000, "ip": "203.0.113.5", "method": "GET", "path": "/", "result": 200, "ua": "...", "referer": "..."}
  ],
  "total": 1,
  "offset": 0,
  "pageSize": 100
}

イベントログの取得

GET/v1/api/canals/{canal_id}/events?offset=0&category=

canal への管理イベント（作成・転送先変更・保護の変更・一時停止/再開・削除・有効期限切れの自動削除・証明書の発行/更新失敗など）を新しい順・100 件/頁で返します。訪問者のアクセス記録はアクセスログ、こちらは「誰が・いつ・どの IP から・何をしたか」の台帳です（保持 365 日）。

パラメータ		型	説明
offset	任意	integer	取得開始位置（既定 0・1 頁 100 件）
category	任意	string	`operation`（操作）/`system`（自動処理）/`limit`（制限）/`error`（エラー）で絞り込み

curl -sS -H "Authorization: Bearer $KEY"      "https://app.wirecanal.com/v1/api/canals/{canal_id}/events?category=operation"

{
  "entries": [
    {
      "event_id": 123,
      "ts": 1720000000000,
      "category": "operation",
      "event_type": "canal.forward_target_updated",
      "canal_id": "ab12",
      "hostname": "ab12xyz0.ja001.wirecanal.com",
      "actor": "api",
      "actor_uid": "…",
      "api_key_id": "ak_…",
      "ip": "203.0.113.5",
      "detail": {"from": "localhost:3000", "to": "localhost:8080"}
    }
  ],
  "total": 1,
  "offset": 0,
  "pageSize": 100
}

actorはuser（ダッシュボード操作）/api（このときapi_key_idでどの API キーによる操作かまで特定できます）/operator（運営）/system（自動処理）。ipは操作元の実際の接続元です（運営操作と自動処理では返しません）。canal を削除した後の履歴はダッシュボードの「イベント履歴」で確認できます。

移管を依頼する

POST/v1/api/canals/{canal_id}/transfer

canal のオーナーシップを別の WireCanal ユーザーへ移すための依頼を送ります（依頼 → 相手の受け入れの 2 段階・双方プロ以上）。公開ホスト名・アクセス保護・アクセスログ・独自ドメインは canal と一緒に移り、成立と同時に access_key が再発行されて依頼者側の wirecanal.json は無効になります。API キーは移りません。

パラメータ		型	説明
to_email	必須	string	宛先メールアドレス。宛先が WireCanal ユーザーかどうかは応答・所要時間のどちらにも現れません

curl -sS -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json"      -d '{"to_email": "teammate@example.com"}'      "https://app.wirecanal.com/v1/api/canals/{canal_id}/transfer"

{
  "transfer": {
    "status": "pending",
    "request_id": "tr_1a2b3c4d",
    "to_email": "teammate@example.com",
    "created_at": 1720000000000,
    "expires_at": 1720604800000
  }
}

対象は期限のない canal のみ（期限付きは 400not_transferable）。依頼は 7 日で自動失効し、1 つの canal に受け入れ待ちの依頼は 1 件だけです（重複は 409already_requested）。同時に依頼中にできるのは 10 件・同じ宛先へは 24 時間に 1 件（超過は 429rate_limited）。宛先には案内メールが届きます（依頼者の名前・メールアドレスは載りません）。canal 表現には受け入れ待ちの依頼がtransferフィールドとして載ります（無ければnull）。

依頼を取り消す

POST/v1/api/canals/{canal_id}/transfer/cancel

受け入れ待ちの移管依頼を取り消します。宛先の受け入れ一覧からも消えます（宛先への通知は送られません）。受け入れ待ちの依頼が無い場合は 404 です。

{"success": true}

移管の一覧

GET/v1/api/transfers

received（自分宛の受け入れ待ち＝API キーの持ち主のメールアドレスで照合・依頼者の情報は載りません）とsent（自分が出した依頼の履歴）を返します。

{
  "received": [
    {
      "request_id": "tr_9z8y7x6w",
      "hostname": "ab12xyz0.ja001.wirecanal.com",
      "tcp_endpoint": null,
      "type": "http",
      "has_custom_domain": false,
      "created_at": 1720000000000,
      "expires_at": 1720604800000
    }
  ],
  "sent": [
    {
      "request_id": "tr_1a2b3c4d",
      "canal_id": "ab12",
      "hostname": "cd34abcd.ja001.wirecanal.com",
      "type": "http",
      "to_email": "teammate@example.com",
      "to_email_masked": false,
      "status": "accepted",
      "created_at": 1719000000000,
      "expires_at": 1719604800000,
      "accepted_at": 1719100000000
    }
  ]
}

sentの宛先（to_email）は、依頼が終端状態（受け入れ済み・取り消し・期限切れ）になってから 30 日で***@maskedにマスクされます。

移管を受け入れる

POST/v1/api/transfers/{request_id}/accept

自分宛の移管依頼を受け入れます。権限は「API キーの持ち主のメールアドレス = 依頼の宛先」だけです（宛先が自分でない・期限切れ・取り消し済みはすべて 404 の同一応答）。受け入れ側もプロ以上と canal の空き枠が必要で、TCP/MCP canal はその種別を作れるプラン、独自ドメイン付きは独自ドメイン対応プランが必要です。1 つでも満たさなければ何も変わりません（fail-closed）。

curl -sS -X POST -H "Authorization: Bearer $KEY"      "https://app.wirecanal.com/v1/api/transfers/tr_9z8y7x6w/accept"

成立すると canal 表現に加えてagent_json（新しい wirecanal.json の中身）が返ります。依頼者側の以前の wirecanal.json は即座に無効になり、接続中のトンネルも自動的に切断されます。移管前のイベントログは新しいオーナーには引き継がれません。

{
  "canal_id": "ab12",
  "hostname": "ab12xyz0.ja001.wirecanal.com",
  "transfer": null,
  "agent_json": {
    "access_key": "ck_（新しく発行されたキー）",
    "forward_target": "localhost:3000"
  }
}

接続キーの一覧

GET/v1/api/canals/{canal_id}/auth-keys

canal の公開エンドポイントを固定キーで守る「接続キー」の一覧です。OAuth に対応しない MCP クライアント（Claude Code・Gemini CLI などの「その他の AI」）が毎リクエストに付けるキーを、利用者・部署ごとに分けて発行し、個別に失効できます。API の操作キー（wk_）とは別物で、キーの値そのものは一覧には含まれません（発行時に一度だけ表示）。

curl -sS -H "Authorization: Bearer $KEY"      "https://app.wirecanal.com/v1/api/canals/{canal_id}/auth-keys"

{
  "keyauth_enabled": true,
  "keys": [
    {
      "key_id": "mk_1a2b3c4d",
      "label": "eigyo-team",
      "header_name": "",
      "expires_at": 1728000000000,
      "revoked_at": null,
      "created_at": 1719000000000,
      "last_used_at": 1719100000000
    }
  ]
}

keyauth_enabledは接続キー認証そのものの有効/無効です（キーを発行すると自動で有効になります）。header_nameが空のキーはAuthorization: Bearer <キー>で、名前があるキーはそのヘッダー（例X-API-Key）で照合されます。

接続キーを発行する

POST/v1/api/canals/{canal_id}/auth-keys

接続キーを発行します。キーの値（mk_で始まる平文）はこの応答に一度だけ含まれ、以後は取得できません。接続元 IP を絞れないサービス向けには、有効期限を付けて定期的に入れ替えることをおすすめします。有効なキーは canal あたり 20 本までです。

パラメータ		型	説明
label	必須	string	利用者・部署などの名前（1〜64 文字）
header	任意	string	照合に使うヘッダー名。省略時は`Authorization: Bearer`形
expires_in_days	任意	number	有効日数（1〜3650）。省略時は無期限

curl -sS -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json"      -d '{"label": "eigyo-team", "expires_in_days": 90}'      "https://app.wirecanal.com/v1/api/canals/{canal_id}/auth-keys"

{
  "key_id": "mk_1a2b3c4d",
  "label": "eigyo-team",
  "header": "authorization",
  "expires_at": 1728000000000,
  "plaintext": "mk_（キーの値・この応答限り）"
}

発行後は、公開側へのアクセスがこのキーで認証されます（不一致・欠落は 401）。どのキーで通ったかはアクセスログにkey_idとして残ります（キーの値は記録されません）。

接続キーを失効させる

DELETE/v1/api/canals/{canal_id}/auth-keys/{key_id}

キーを個別に失効させます（元に戻せません）。失効は即時反映され、エッジ側にも最大 60 秒で行き渡ります。存在しない・他人の・失効済みのキーはいずれも 404 の同一応答です。

{"success": true}

対応サービスの一覧（MCP canal）

GET/v1/api/canals/{canal_id}/connectors

MCP canal の「対応サービス（どの AI から使うか）」の状態一覧です。有効化すると、その AI に必要な認証設定（OAuth クライアントなど）が canal に自動で入ります。ダッシュボードの「MCP 接続」タブと同じ仕組みです。authはそのサービスの認証方式（oauth/none）です。MCP 以外の canal は 400bad_typeです。

{
  "connectors": [
    {"name": "claude",   "label": "Claude",   "auth": "oauth", "available": true, "enabled": true,  "client_id": "oc_25f053ba349f"},
    {"name": "chatgpt",  "label": "ChatGPT",  "auth": "oauth", "available": true, "enabled": false, "client_id": null},
    {"name": "grok",     "label": "Grok",     "auth": "oauth", "available": true, "enabled": false, "client_id": null},
    {"name": "bestllam", "label": "Bestllam", "auth": "oauth", "available": true, "enabled": false, "client_id": null},
    {"name": "public",   "label": "公開（テスト）", "auth": "none", "available": true, "enabled": false}
  ]
}

対応サービスを有効化する

PUT/v1/api/canals/{canal_id}/connectors/{name}

nameはbestllam/claude/chatgpt/grok/public。有効化は冪等です（もう一度呼んでも設定は増えません）。

Bestllam / Claude / ChatGPT / Grok: 接続用の OAuth クライアントを自動発行します。応答のclient_secretはこの一度だけです。AI サービスのコネクタ設定（OAuth の詳細設定）に貼り付けると、接続時に WireCanal の許可画面が開き、canal のオーナーが許可すると接続が成立します
public: 認証なしのテスト公開を期限つき（7 日）で記録します。期限が来ると自動終了し、認証必須に切り替わります

curl -sS -X PUT -H "Authorization: Bearer $KEY"      "https://app.wirecanal.com/v1/api/canals/{canal_id}/connectors/claude"

{
  "name": "claude",
  "enabled": true,
  "client_id": "oc_25f053ba349f",
  "client_secret": "os_（クライアントシークレット・この応答限り）"
}

対応サービスを無効化する

DELETE/v1/api/canals/{canal_id}/connectors/{name}

Bestllam / Claude / ChatGPT / Grok（name=bestllam/claude/chatgpt/grok）は接続用クライアントを失効させ、発行済みのアクセスも止まります。public はテスト公開の記録を消します。もともと無効ならchanged: falseが返ります（冪等）。

{"success": true, "changed": true}

組織 IdP 設定の一覧（MCP の接続許可を会社アカウントで）

GET/v1/api/oauth-idps

MCP canal の「接続の許可」画面のログインを、会社の認証基盤（OIDC・例 Google Workspace）へ委譲するための IdP 設定の一覧です。canal に割り当てると、許可したドメインの組織メンバーが会社アカウントでログインして接続を許可できます（メンバーの WireCanal アカウントは不要・canal オーナー本人のログインでの許可はこれまでどおり）。IdP 側でアカウントを無効化すると、そのメンバーの接続も自動で止まります（アクセスは 1 時間ごとの更新時に確認）。クライアントシークレットは返しません（has_secretのみ）。プロ以上のプランで利用できます（設定の追加・割当は機能なしプランで 403plan_required）。スクリーンショット付きの設定手順は組織のメンバーに使ってもらうガイドをご覧ください。

{
  "idps": [
    {"idp_id": "oi_1a2b3c4d5e6f", "label": "社内 Google Workspace", "issuer_url": "https://accounts.google.com",
     "client_id": "xxxx.apps.googleusercontent.com", "has_secret": true, "allowed_domains": ["example.co.jp"]}
  ]
}

組織 IdP 設定を追加する

POST/v1/api/oauth-idps

会社の認証基盤（OIDC 対応）に WireCanal をクライアントとして登録し、その値をここに保存します。IdP 側のリダイレクト URI にはhttps://app.wirecanal.com/oauth/idp/callbackを登録してください。保存前にissuer_urlの実在（OIDC discovery）を確認します（到達できないときは 400bad_issuer）。

パラメータ		型	説明
issuer_url	必須	string	OIDC issuer（例`https://accounts.google.com`・https のみ）
client_id	必須	string	IdP に登録したクライアント ID
client_secret	任意	string	クライアントシークレット（保存後は再表示されません）
allowed_domains	必須	array / string	接続の許可を認めるメールドメイン（完全一致・1 つ以上。カンマ区切り文字列でも可）
label	任意	string	表示名

curl -sS -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json"      -d '{"label": "社内 Google Workspace", "issuer_url": "https://accounts.google.com", "client_id": "xxxx.apps.googleusercontent.com", "client_secret": "…", "allowed_domains": ["example.co.jp"]}'      "https://app.wirecanal.com/v1/api/oauth-idps"

組織 IdP 設定を削除する

DELETE/v1/api/oauth-idps/{idp_id}

設定を削除します。この IdP 経由で発行済みの接続の許可はすべて失効し、割当中の canal からも自動的に外れます。

{"success": true}

canal へ IdP を割り当てる / 状態 / 解除

PUT/v1/api/canals/{canal_id}/idp

MCP canal に IdP を割り当てます（body は{"idp_id": "oi_…"}・冪等）。MCP 以外の canal は 400bad_type、自分の設定に無い IdP は 404idp_not_foundです。別の IdP へ付け替えると、以前の IdP 経由の許可は失効します。

GET/v1/api/canals/{canal_id}/idp

割当状態を返します（未割当は{"idp_id": null}）。

DELETE/v1/api/canals/{canal_id}/idp

割当を解除します。この IdP 経由で発行済みの接続の許可は失効します（オーナー本人の許可は変わりません）。もともと未割当ならchanged: falseが返ります（冪等）。

curl -sS -X PUT -H "Authorization: Bearer $KEY" -H "Content-Type: application/json"      -d '{"idp_id": "oi_1a2b3c4d5e6f"}'      "https://app.wirecanal.com/v1/api/canals/{canal_id}/idp"

ツール許可の提案（取得 / 保存 / 取り下げ）

PUT/v1/api/canals/{canal_id}/tool-policy

「どのツールを AI に見せるか」の提案を保存します（MCP canal のみ）。ここが大事な点です:保存されるのは提案だけで、実際の許可台帳（社内のwirecanal.json）は、エージェントを動かしているマシンでwirecanal apply-policyを実行して承認したときにのみ書き換わります（提案と承認の分離）。allowは空白の除去・重複の除去・並び替えをしたうえで保存されます（各 1〜128 文字・256 個まで）。

パラメータ		型	説明
default	任意	string	`deny`（選んだツールだけ許可・既定）または`allow`（原則すべて許可）
allow	任意	string[]	許可するツール名の一覧
deny_destructive	任意	boolean	破壊的な名前のツール（delete/drop 等）は許可リストにあっても拒否する
hide_denied_in_list	任意	boolean	拒否したツールをツール一覧応答にも出さない

curl -sS -X PUT -H "Authorization: Bearer $KEY" -H "Content-Type: application/json"      -d '{"default": "deny", "allow": ["get_sales_summary", "search_products"], "deny_destructive": true}'      "https://app.wirecanal.com/v1/api/canals/{canal_id}/tool-policy"

GET/v1/api/canals/{canal_id}/tool-policy

提案と指紋を返します（提案なしはpolicy: null）。desired_fpは提案の指紋、last_tools_fpはエージェント（v0.17 以上）が最後に申告した実効設定の指紋で、両者が一致していれば提案は適用済みです（ダッシュボードの「適用済み／未承認の変更あり」表示と同じ判定材料）。

{
  "policy": {
    "allow": ["get_sales_summary", "search_products"],
    "default": "deny",
    "deny_destructive": true,
    "hide_denied_in_list": false
  },
  "desired_fp": "f01fc5b0ded997fc",
  "last_tools_fp": "f01fc5b0ded997fc"
}

DELETE/v1/api/canals/{canal_id}/tool-policy

提案を取り下げます。エージェント側で反映済みの設定には影響しません。もともと提案が無ければchanged: falseが返ります（冪等）。

形式・上限の検証エラーは 400bad_tool_policy、MCP 以外の canal は 400bad_typeです。

独自ドメインを接続する

POST/v1/api/canals/{canal_id}/custom-domain

お持ちのドメイン（例app.example.co.jp）を canal に接続します（独自ドメイン対応プラン・HTTP/MCP canal のみ）。登録すると、設定すべき DNS レコードがcustom_domain.required_dns_recordsとして返ります。ダッシュボードの接続ジャーニーと同じ仕組みなので、途中まで API・続きは画面、のような使い分けもできます。

パラメータ		型	説明
domain	必須	string	接続するドメイン（サブドメイン・apex・ワイルドカード`*.example.co.jp`形）

curl -sS -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json"      -d '{"domain": "app.example.co.jp"}'      "https://app.wirecanal.com/v1/api/canals/{canal_id}/custom-domain"

{
  "custom_domain": {
    "domain": "app.example.co.jp",
    "status": "dns_pending",
    "required_dns_records": [
      {"method": "cname", "type": "CNAME", "name": "app.example.co.jp", "value": "ab12xyz0.ja001.wirecanal.com"},
      {"method": "a_txt", "type": "A",     "name": "app.example.co.jp", "value": "203.0.113.10"},
      {"method": "a_txt", "type": "TXT",   "name": "_wirecanal-verify.app.example.co.jp", "value": "wcv_..."}
    ],
    "shard_apex": "ja001.wirecanal.com"
  }
}

required_dns_recordsはmethod でどちらか一方式を選んで設定します: サブドメインならcnameの 1 行、apex（CNAME を置けないドメイン直下）ならa_txtの A ＋ TXT。A の値が取得できなかったときはshard_apexの名前を解決して同じ値を設定できます。設定すべきレコードは、接続が完了するまで canal 詳細の GET にも同梱されます。

同じdomainをもう一度 POST した場合はエラーにならず現在の状態を 200 で返します（リトライしても安全）。別のドメインへ変えるときは解除→再登録です（409already_attached）。他の canal が使用中のドメインは 409domain_taken、プラン不足は 403plan_required_domainです。

ワイルドカード（*.example.co.jp形）も指定できます。配下のサブドメイン（1 階層）とドメイン直下を 1 枚の証明書でまとめて接続でき、required_dns_recordsには CNAME 2 本が返ります: ①トラフィック用（*.example.co.jp→ canal の内部ホスト名）②証明書発行用（_acme-challenge.example.co.jp→ 登録時に払い出される専用の名前。1 回設定すれば、以後の証明書の自動更新も同じ 1 本で回ります）。2 本とも設定して DNS 確認が通ると、証明書の発行まで自動で進みます。app.example.co.jpのように単体で接続した独自ドメインがある場合は、そのホスト名についてはそちらが常に優先されます。

ドメインの DNS 確認

POST/v1/api/canals/{canal_id}/custom-domain/verify

DNS レコードの設定を確認します。確認が通ると、証明書の自動発行までそのまま進みます（ダッシュボードと同じ動き）。あとは canal 詳細の GET でcustom_domain.statusがactiveになるまで待つだけです（発行は通常 1〜2 分）。

{
  "verified": true,
  "issue": {"kicked": true, "status": "issuing"}
}

{
  "verified": false,
  "observed": {"cname": null, "a": [], "txt": []},
  "message": "CNAME が見つかりません。DNS の反映をお待ちください。"
}

確認に失敗しても状態は変わらず、何度でも呼べます。observedは「レコードが今どう見えているか」なので、設定値との突き合わせに使えます。発行の試行には上限（5 回/時）があり、超えたときはissue.error = "rate_limited"と再試行可能時刻が返ります（確認自体は成功のまま・時間を置いて再度 verify）。発行が始まっている/開通済みのときの確認は 400bad_stateです。

独自ドメインの接続を解除

DELETE/v1/api/canals/{canal_id}/custom-domain

接続を解除します（どの状態からでも可）。確認用の TXT 値は破棄され、再登録すると新しい値が払い出されます。ドメインを接続していない canal への DELETE は 404 です。

{"success": true}

OpenAPI 仕様

機械可読の正本はOpenAPI 3.1です。認証なしで公開しています:

GEThttps://app.wirecanal.com/v1/api/openapi.json

本リファレンスに記載の全エンドポイント・パラメータ・応答形式を、機械可読の形で取得できます。

API キーを発行する対応プランを見る

WireCanal API リファレンス

概要と対応プラン

認証

レート制限

エンドポイント

枠の確認

エッジ一覧

canal 一覧

canal 作成

canal 詳細

転送先・アクセス保護の更新

パス別の追加条件（path.rules[].require）

よくあるスキャンパスの一括遮断（path.scanner_block）

canal 削除

公開の一時停止

公開の再開

wirecanal.json の取得

複数 canal をまとめて取得

まとめ運用の組の記録

アクセスログの取得

イベントログの取得

移管を依頼する

依頼を取り消す

移管の一覧

移管を受け入れる

接続キーの一覧

接続キーを発行する

接続キーを失効させる

対応サービスの一覧（MCP canal）

対応サービスを有効化する

対応サービスを無効化する

組織 IdP 設定の一覧（MCP の接続許可を会社アカウントで）

組織 IdP 設定を追加する

組織 IdP 設定を削除する

canal へ IdP を割り当てる / 状態 / 解除

ツール許可の提案（取得 / 保存 / 取り下げ）

独自ドメインを接続する

ドメインの DNS 確認

独自ドメインの接続を解除

OpenAPI 仕様

パス別の追加条件（`path.rules[].require`）

よくあるスキャンパスの一括遮断（`path.scanner_block`）