Localtonet REST API
このページの内容 8セクション
REST API v2では、ダッシュボードでトンネルに対して行える操作(作成、開始、停止、削除、設定)に加えて、AuthToken、トークングループ、SSOプロバイダーの管理もできます。すべてのリクエストは、APIキーで認証します。
インタラクティブリファレンス #
すべてのエンドポイントについて、リクエストとレスポンスのモデルと、試せるフォームを、インタラクティブリファレンスで確認できます。
- localtonet.com/api:API v2(現行バージョン)。ダッシュボードのAPI UIボタンからも開けます。
- localtonet.com/api/v1:API v1(既存の連携のために残してあります)。新しく開発する場合はv2を使ってください。
このページでは、規約とエンドポイントグループの概要を説明します。リクエストの正確なフィールドについては、リファレンスでエンドポイントを開いてください。
始める前に #
- APIキー。ダッシュボードを開き、APIキーカードのコピーを使います。アカウントとセキュリティをご覧ください。
- トンネルを作成する場合:トンネルを実行するデバイスのAuthTokenと、そのトークンで接続されたLocaltonetクライアント。AuthTokenをご覧ください。
APIキーは非公開にしてください。キーを持っている人は、あなたのトンネルとトークンを作成、変更、削除できます。APIキーカードの変更を選ぶと、新しいキーが作成され、古いキーは無効になります。
ベースURLと認証 #
v2のすべてのエンドポイントは、次で始まります。
https://localtonet.com/api/v2すべてのリクエストのAuthorizationヘッダーに、APIキーをBearerトークンとして付けて送信します。
GET /api/v2/tunnels HTTP/1.1
Host: localtonet.com
Authorization: Bearer <YOUR_API_KEY>チームのダッシュボードでコピーしたAPIキーでは、そのチームのAuthTokenとトンネルが一覧表示されます。自分のアカウントのキーでは、どのチームにも属さないAuthTokenが一覧表示されます。
規約 #
| 項目 | APIの動作 |
|---|---|
| 形式 | リクエストとレスポンスの本文はJSONです。本文を送るときはContent-Type: application/jsonを付けます。 |
| トンネルID | パス内のtunnelIdは、一覧と作成のエンドポイントが返す、トンネルの数値のidです。 |
| パス内のAuthToken | {token}は、AuthTokenの文字列そのものです。 |
| 成功コード | 読み取りでは本文付きの200、ほとんどの作成では201(トンネル作成のエンドポイントは新しいトンネルを返します)、ほとんどの操作と更新では本文なしの204です。各エンドポイントのレスポンスはリファレンスに記載されています。 |
| 一括エンドポイント | パスに/bulk/を含むエンドポイントは、JSON配列を受け取り、1回のリクエストで最大100件まで処理できます(/tunnels/bulk/protocol-typeは最大500件)。 |
| 新しいトンネル | 作成したトンネルは、まだ実行されていません。開始アクションで開始してください。proxy/with-detailエンドポイントだけは、isStartAfterCreateによって同じ呼び出しでトンネルを開始できます。 |
エラー #
| ステータス | 意味 | 本文 |
|---|---|---|
400 | リクエスト本文が正しくないか、プランの上限などの理由で操作が拒否されました。 | ほとんどのエンドポイントでは、JSONのproblemオブジェクトで、titleにメッセージが入ります。検証エラーと一括エンドポイントのエラーは、errorsに一覧表示されます。 |
401 | APIキーがないか、無効です。 | 特定のメッセージなし |
403, 409 | 一部のトンネル設定とVPNアクセスのエンドポイントが、変更が許可されていない場合、または現在の構成と競合する場合に返します。 | titleにメッセージが入ったproblemオブジェクト。 |
404 | トンネルまたはオブジェクトが見つからないか、あなたのものではありません。 | 空、またはproblemオブジェクト |
429 | リクエストが多すぎます。 | 下の「レート制限」をご覧ください。 |
レート制限 #
リクエストにはレート制限があります。制限を超えたリクエストには429 Too Many Requestsが返されます。少し待ってから再送してください。個別の呼び出しを何度も行う代わりに、一括エンドポイントを使ってください。
例 #
<YOUR_API_KEY>は自分のAPIキーに、<YOUR_TOKEN>はデバイスのAuthTokenに置き換えてください。
トンネルを一覧表示する #
curl https://localtonet.com/api/v2/tunnels \
-H "Authorization: Bearer <YOUR_API_KEY>"レスポンスは、トンネルごとに1つのオブジェクトを含むJSON配列です。フィールドにはid、title、url(公開アドレス)、protocolType、authToken、serverId、clientIpとclientPort(ローカルのターゲット)、status、connectionStatusなどがあります。まだトンネルがない場合、レスポンスは空の配列ではなく404です。
ランダムなサブドメインでHTTPトンネルを作成する #
まず、使いたいサーバーのコードを取得します。
curl https://localtonet.com/api/v2/servers \
-H "Authorization: Bearer <YOUR_API_KEY>"各エントリには、serverCode、serverName、serverDomainがあります。次に、トンネルを作成します。この例では、デバイスのポート3000で動作するWebアプリに転送します。
curl -X POST https://localtonet.com/api/v2/tunnels/http/random-subdomain \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"authToken": "<YOUR_TOKEN>",
"serverCode": "<SERVER_CODE>",
"protocolType": 1,
"ip": "127.0.0.1",
"port": 3000
}'| フィールド | 意味 | 値 |
|---|---|---|
authToken | トンネルを実行するデバイスのAuthToken。 | 必須 |
serverCode | サーバー。GET /serversから取得します。 | 必須 |
protocolType | トンネルの種類。 | 1 HTTP、5 File Server、24 MCP Gateway |
ip | トンネルが転送するローカルIPアドレス。 | 有効なIPアドレス。たとえば127.0.0.1 |
port | ローカルポート。 | 1~65534 |
path | 共有するローカルフォルダー。 | ファイルサーバーの場合のみ必須 |
レスポンスは、新しいトンネルを含む201 Createdです。そのidとurlを控えておいてください。
トンネルを開始する #
curl -X POST https://localtonet.com/api/v2/tunnels/<TUNNEL_ID>/actions/start \
-H "Authorization: Bearer <YOUR_API_KEY>"レスポンスは204 No Contentです。デバイスのクライアントが接続されていれば、トンネルはurlで到達できるようになります。再び停止するには、/actions/stopを使います。
エンドポイントグループ #
以下のパスはすべて、https://localtonet.com/api/v2からの相対パスです。
トンネル #
| メソッド | パス | 用途 |
|---|---|---|
| GET | /tunnels | すべてのトンネルを一覧表示します。 |
| GET | /tunnels/{tunnelId} | 1つのトンネルを取得します。 |
| POST | /tunnels/http/random-subdomain | ランダムなサブドメインで、HTTP、ファイルサーバー、またはMCPゲートウェイのトンネルを作成します。 |
| POST | /tunnels/http/custom-subdomain | 自分で選んだサブドメインでトンネルを作成します。 |
| POST | /tunnels/http/custom-domain | 自分のドメインでトンネルを作成します。 |
| POST | /tunnels/tcp-udp | TCP、UDP、またはTCPとUDPを組み合わせたトンネルを作成します。 |
| POST | /tunnels/proxy | HTTP、SOCKS5、Shadowsocks、またはVLESSのプロキシトンネルを作成します。 |
| POST | /tunnels/proxy/with-detail | プロキシトンネルを作成し、その接続の詳細をすべて返します。 |
| POST | /tunnels/shared-proxy | 共有(ローテーティング)プロキシトンネルを作成します。 |
| POST | /tunnels/{tunnelId}/actions/start | トンネルを開始します。 |
| POST | /tunnels/{tunnelId}/actions/stop | トンネルを停止します。 |
| DELETE | /tunnels/{tunnelId} | トンネルを完全に削除します。 |
| PATCH | /tunnels/{tunnelId}/title | タイトルを変更します。 |
| PATCH | /tunnels/{tunnelId}/local-ip | ローカルIPアドレスを変更します。 |
| PATCH | /tunnels/{tunnelId}/local-port | ローカルポートを変更します。 |
| PATCH | /tunnels/{tunnelId}/port-reserved | TCP/UDPトンネルのポート予約をオンまたはオフにします。 |
| PATCH | /tunnels/{tunnelId}/legacy-connect | レガシー接続モードをオンまたはオフにします。 |
| PATCH | /tunnels/{tunnelId}/protocol-type | プロキシトンネルのプロキシプロトコルを変更します。 |
| GET | /tunnels/{tunnelId}/request-logs | HTTPまたはファイルサーバーのトンネルの、最近のHTTPリクエストログ。 |
一括トンネル操作 #
| メソッド | パス | 用途 |
|---|---|---|
| POST | /tunnels/bulk/http/random-subdomain | ランダムなサブドメインで、複数のHTTPトンネルを作成します。 |
| POST | /tunnels/bulk/http/custom-subdomain | カスタムサブドメインで、複数のトンネルを作成します。 |
| POST | /tunnels/bulk/http/custom-domain | カスタムドメインで、複数のトンネルを作成します。 |
| POST | /tunnels/bulk/tcp-udp | 複数のTCP/UDPトンネルを作成します。 |
| POST | /tunnels/bulk/proxy | 複数のプロキシトンネルを作成します。 |
| POST | /tunnels/bulk/proxy/with-detail | 複数のプロキシトンネルを作成し、その接続の詳細を返します。 |
| POST | /tunnels/bulk/shared-proxy | 複数の共有(ローテーティング)プロキシトンネルを作成します。 |
| POST | /tunnels/bulk/actions/start | 複数のトンネルを開始します。本文:トンネルIDの配列。たとえば[123, 456]。 |
| POST | /tunnels/bulk/actions/stop | 複数のトンネルを停止します。本文:トンネルIDの配列。 |
| DELETE | /tunnels/bulk | 複数のトンネルを削除します。本文:トンネルIDの配列。 |
| PATCH | /tunnels/bulk/protocol-type | 複数のプロキシトンネルのプロキシプロトコルを変更します。 |
トンネルの設定 #
これらのエンドポイントは、1つのトンネルの設定を変更します。すべて/tunnels/{tunnelId}で始まります。各設定の内容は設定リファレンスで説明しています。
| メソッド | /tunnels/{tunnelId}の後のパス | 用途 |
|---|---|---|
| GET、POST、PATCH、DELETE | /ip-restrictions | IP制限の一覧表示、追加、許可モードまたは拒否モードの設定、すべての削除。1件だけ削除するには/ip-restrictions/{restrictionId}を使います。 |
| GET、POST、PATCH、DELETE | /access-controls | URLパスのアクセス制御についても同様です。1件だけ削除するには/access-controls/{controlId}を使います。 |
| GET、PATCH | /headers | カスタムHTTPヘッダー。 |
| GET、PATCH | /authentication | HTTPベーシック認証。 |
| GET、PATCH | /expiration | トンネルの有効期限。 |
| GET、PATCH | /server-port | TCP/UDPトンネルのサーバー側ポート。 |
| GET、PATCH | /http-timeout | HTTPリクエストのタイムアウト。 |
| GET、PATCH | /rate-limit | 速度制限。 |
| GET、PATCH | /bandwidth-limit | 総データ転送量の制限。 |
| GET | /bandwidth-usage | 現在の帯域幅使用量。カウンターはPOST /bandwidth-usage/resetでリセットします。 |
| GET、PATCH | /arguments | トンネルのカスタムコマンドライン引数。 |
| GET、POST | /shared-proxy-clients | 共有(ローテーティング)プロキシトンネルのクライアントを一覧表示または追加します。更新または削除するには、PATCHまたはDELETE /shared-proxy-clients/{clientId}を使います。 |
| GET | /advanced-settings | トンネルのすべての詳細設定を1つのレスポンスで取得します。 |
| GET、PATCH | /ipv4-only, /wifi-split, /proxy-protocol, /pass-through, /https-only, /http3 | 1つの詳細設定を読み取り、または切り替えます。 |
| PATCH | /ssl-stream | SSLストリーム設定を切り替えます。 |
| GET、PATCH | /file-path, /host-header, /path-rewrite, /upstream-proxy, /note, /vless | 1つの値を読み取り、または変更します。 |
| GET、PUT | /token-groups | トンネルに割り当てられたトークングループ。 |
| GET、PATCH | /server | トンネルのサーバー。 |
AuthToken #
| メソッド | パス | 用途 |
|---|---|---|
| GET | /auth-tokens | AuthTokenを一覧表示します。 |
| GET | /auth-tokens/detail | AuthTokenを詳細付きで一覧表示します。 |
| GET | /auth-tokens/{token} | 1つのAuthTokenの詳細。 |
| POST | /auth-tokens | AuthTokenを作成します。 |
| DELETE | /auth-tokens/{token} | AuthTokenを削除します。 |
| GET | /auth-tokens/{token}/tunnels | AuthTokenのトンネル。 |
| GET | /auth-tokens/{token}/ip-history | デバイスのパブリックIPアドレスの変更履歴。 |
| GET、PATCH | /auth-tokens/{token}/airplane-mode-settings | 機内モード自動化の設定。 |
| POST | /auth-tokens/{token}/change-ip-links/{airplaneModeSettingId} | IP変更リンクを追加します。 |
| DELETE | /auth-tokens/{token}/change-ip-links/{id} | IP変更リンクを削除します。 |
| POST | /auth-tokens/{token}/restart-device-links/{airplaneModeSettingId} | デバイス再起動リンクを追加します。 |
| DELETE | /auth-tokens/{token}/restart-device-links/{id} | デバイス再起動リンクを削除します。 |
| GET、PATCH | /auth-tokens/{token}/arguments | AuthTokenに保存されたクライアント引数。 |
トークングループ #
| メソッド | パス | 用途 |
|---|---|---|
| GET | /token-groups | トークングループを一覧表示します。 |
| GET | /token-groups/{id} | 1つのトークングループを取得します。 |
| POST | /token-groups | トークングループを作成します。 |
| DELETE | /token-groups/{id} | トークングループを削除します。 |
| POST | /token-groups/{id}/auth-tokens | グループにAuthTokenを追加します。 |
| DELETE | /token-groups/{id}/auth-tokens/{tokenId} | グループからAuthTokenを削除します。 |
サーバー #
| メソッド | パス | 用途 |
|---|---|---|
| GET | /servers | トンネルを作成できるサーバーを、作成リクエストで使うserverCodeとともに一覧表示します。 |
SSOプロバイダー #
| メソッド | パス | 用途 |
|---|---|---|
| GET | /sso-providers | SSOプロバイダーを一覧表示します。 |
| GET | /sso-providers/default-endpoints | SSOプロバイダーの種類ごとの既定のエンドポイント。 |
| POST | /sso-providers | SSOプロバイダーを作成または更新します。 |
| DELETE | /sso-providers/{id} | SSOプロバイダーを削除します。 |
| GET | /sso-providers/tunnel/{tunnelId} | トンネルに設定されているSSOプロバイダー。ここでのtunnelIdは、トンネルのGUID(guidId)です。 |
| PUT | /sso-providers/tunnel/{tunnelId} | トンネルのSSOプロバイダーを保存します。 |
プロバイダーの役割については、シングルサインオンをご覧ください。
VPNアクセス #
VPNアクセスでは、プロキシトンネル上にWireGuardまたはOpenVPNのデバイスプロファイルが提供され、そのデバイスのすべてのトラフィックがプロキシ経由で外部に出ます。これらのエンドポイントは/tunnels/{tunnelId}/vpn-accessで始まります。
| メソッド | /tunnels/{tunnelId}/vpn-accessの後のパス | 用途 |
|---|---|---|
| GET | (なし) | トンネルのVPNデバイスを一覧表示します。 |
| POST | (なし) | VPNデバイスを作成します。 |
| DELETE | /{peerId} | VPNデバイスを削除(失効)します。 |
| POST | /{peerId}/regenerate | VPNデバイスのキーを再生成します。 |
| GET | /{peerId}/config | VPNデバイスの設定ファイルをダウンロードします。 |
| GET | /{peerId}/qr | WireGuardデバイス設定のQRコード。 |
| GET | /{peerId}/credentials | OpenVPNデバイスのユーザー名とパスワード。 |
トラブルシューティング #
すべてのリクエストが401を返す
ヘッダーを確認してください。Authorization: Bearerの後に半角スペースとキーを続け、キーを引用符で囲まない形式にする必要があります。APIキーカードで変更を選んだ場合、古いキーは使えなくなります。新しいキーをコピーしてください。
チームのAuthTokenが表示されない
自分のアカウントのAPIキーを使っています。チームのダッシュボードに切り替えて、そこでAPIキーをコピーしてください。
トンネルは作成されたが、アドレスが応答しない
新しいトンネルは停止状態です。POST /tunnels/{tunnelId}/actions/startを呼び出し、デバイスのLocaltonetクライアントが、使用したAuthTokenで動作していることを確認してください。
429 Too Many Requestsが返される
リクエストにはレート制限があります。少し待ってからリクエストを再送し、個別の呼び出しを繰り返すループは、1回の一括リクエストに置き換えてください。