twingate-api

役割

このスキルは、Twingate の GraphQL API、サービスアカウントキー管理、CLI ツール、API を利用した自動化を担当します。スクリプト作成、CI/CD パイプラインとの統合、ページネーション、レート制限、トークンの権限設定、コネクターおよびサービスアカウントの認証情報をプログラムからプロビジョニングする方法を扱います。IaC に取って代わるものではありません。スクリプト作成や自動化に使用し、ライフサイクル管理が必要な長期運用の Twingate オブジェクトの管理には使用しないでください。

判断基準とガイドライン

• ミューテーションのレスポンスでは、entity を読み取る前に必ず ok を確認してください。 ミューテーションは、ok: false および entity: null とともに HTTP 200 を返すことがあります。先に ok を確認せずにエンティティのフィールドを読み取ると、null 参照エラーや、気付かないままデータが破損する原因になります。失敗時には error.errorCode と error.message を確認してください。
• 必ずページネーションを実装してください。一度のページですべての結果を取得できると想定してはいけません。 ページネーションを省略したスクリプトは、エラーを出さずにレコードを見落とします。500 件のリソースのうち 50 件しか取得できないこともあります。pageInfo.hasNextPage が false になるまでループし、各リクエストで pageInfo.endCursor を after 引数として渡してください。
• ID を解析、デコード、生成してはいけません。 Twingate の ID は、Base64 でエンコードされた不透明な NodeID です。API から返された値のまま使用してください。Base64 をデコードして数値部分を推測してはいけません。
• タスクに必要な最小権限のトークンを発行してください。 監視やレポート作成には Read、プロビジョニングには Write を使用します。connectorGenerateTokens とサービスアカウントキーの生成に限り、Provision を使用してください。読み取り専用スクリプトに Provision レベルのトークンを発行してはいけません。
• connectorGenerateTokens は、既存の Connector の認証情報をローテーションします。 デプロイ済みの Connector に対して再度実行すると、現在のトークンが無効になり、新しいトークンで再起動するまで Connector は動作しなくなります。認証情報を再プロビジョニングするときに限って実行してください。「更新」操作として実行してはいけません。
• 永続的な構成管理には、GraphQL を直接使うより Terraform または Pulumi を優先してください。 API はスクリプト作成、自動化、レポート作成に適しています。ライフサイクル管理やドリフト検出が必要な長期運用の Twingate オブジェクトには、IaC が適しています。
• 429 の再試行と Retry-After によるバックオフは、後回しにせず最初から実装してください。 API には 1 分あたりのレート制限があります。429 を無視するスクリプトは、大規模な処理の途中で失敗します。Terraform および Pulumi のプロバイダーはこれを自動的に処理しますが、GraphQL を直接使うスクリプトでは無視してはいけません。
• サービスアカウントキーには有効期限があるため、それを使用するパイプラインにはローテーションのロジックを組み込んでください。 expiresAt を監視し、有効期限が切れる前にローテーションしてください。障害発生後に対応するローテーションでは、パイプラインに支障が生じます。
• どちらも「Twingate CLI」と呼ばれる、互いに無関係なツールが 2 つあります。混同しないでください。 Twingate-Labs/tg-cli（Deno/TypeScript。エクスポート／インポート、トポロジ図の作成）と Twingate-Labs/Twingate-CLI（Python。tgcli としてインストールされ、完全な CRUD 操作と複数テナントのセッションに対応）は別々のプロジェクトで、フラグも異なり、共通の開発履歴もありません。コマンドの構文を案内する前に、ユーザーがどちらを指しているのか確認してください。本番環境での利用を推奨する前に、gh-twingate-solutions-general-scripts.md のようなリポジトリは、サポート対象の製品ではなく、LLM の支援を受けた参考例であることを明記してください。

まずリファレンスを検索する

回答する前に、ユーザー自身が使ったキーワードで references/ を検索し、見つかった内容を引用してください。 ファイル名から分かるのはトピックだけです。ツール名、ベンダー名、正確なフラグ名や環境変数名はファイルの本文に記載されているため、ファイル名だけを調べても見落とします。

grep -ril "cloudwatch" references/     # -> gh-twingate-labs-tg-aws-tag-sync.md
grep -ril "graphviz" references/       # -> gh-twingate-labs-tg-cli.md
grep -ril "jupyter" references/        # -> gh-twingate-labs-twingate-api-intro-with-python.md, gh-twingate-solutions-health-report-generator.md

次の内容を含む質問に回答したり、API コードを記述したりする前に、まず references/graphql-schema-reference.md を読んでください。 これは型とフィールドに関する正式なリファレンスであり、簡単ではないクエリやミューテーションでは、必ず参照する必要があります。

• 正確なクエリ／ミューテーション名、引数名、引数の型
• レスポンスオブジェクトのフィールド名（ネストされたフィールドやページネーション構造を含む）
• 任意のフィールドの列挙値（例：リソースプロトコルの列挙値、アドレスタイプの列挙値）
• 作成／更新ミューテーションの入力型の構造
• 特定のフィールドが存在するか、null 許容か、非推奨か

CLI ツール（Python tgcli、Deno tg-cli、tgcli-web、OpenClaw）については、コマンドを提案する前に、該当する CLI リファレンスを読んでください。フラグ名とサブコマンドの構造はツールごとに異なり、ほぼ同じ名前のツールも 2 つあります。

スキーマや CLI に関する質問に、学習データの記憶から回答しないでください。スキーマは更新され、CLI ツールの構文はバージョンによって異なります。自動化タスク（AWS タグ同期、ヘルスレポート、CI ランナーへのアクセスなど）に使えるツールがあるか尋ねられた場合は、存在しないと答える前に検索してください。

ルーティング

どちらか一方ではなく、併せて有効化してください。 以下の参照先は追加で適用するものです。複数の領域にまたがるプロンプトでは、最初に一致したスキルだけで終わらせず、このスキルに加えて、指定されたスキルの references/ も読み込み、検索してください。同じキーワードで関連スキルの references/ を先に検索し、該当する内容が見つかったら、そのスキル全体を読み込んでください。Twingate に関する回答は複数のスキルにまたがることがよくあるため、参照先は少なくするより多くするようにしてください。よくある関連領域の組み合わせ：特定のオブジェクトの自動化 → そのオブジェクトのスキル（connectors／identity／architect）も参照、永続的なライフサイクル管理 → terraform／pulumi を参照。

• → twingate-terraform / twingate-pulumi：API スクリプトではなく、永続的な IaC 管理をユーザーが求めている場合。IaC では、生の API スクリプトにはないドリフト検出、監査証跡、ライフサイクル管理が得られます
• → twingate-architect：API 自動化を記述する前に、リソース、リモートネットワーク、グループ、コネクターとは何かを把握する場合
• → twingate-connectors：connectorGenerateTokens に関する文脈が必要な場合。トークンのプロビジョニングは API 操作ですが、コネクターのデプロイに関する詳細（実行環境の変数、再起動時の動作）は twingate-connectors に記載されています

参考資料

最新のコーパスは毎週更新されます。現在のコーパスについては references/ を参照してください。ここには 2 種類のファイルと、手動で管理される信頼できる参考資料が 1 つあります。

• graphql-schema-reference.md — 静的な GraphQL SDL で、手動で管理される信頼できる参考資料です。自動再生成は絶対に行わないでください。
• {slug}.md — twingate.com/docs のページ（製品ドキュメント）の要約です。
• gh-{org}-{repo}.md — 公開されている Twingate の GitHub リポジトリ（公式ツール、SE の自動化、コミュニティ統合）の要約です。

ユーザーの質問	最初に読むファイル
クエリ／ミューテーションのシグネチャ、フィールド名、列挙値、入力型	graphql-schema-reference.md（信頼できる参考資料）
API の概要、認証、導入方法	api-overview.md、api.md、getting-started-with-the-api.md
API の探索、クエリの例	exploring-the-apis.md
Python CLI のドキュメントページ（tg-cli）	introduction-to-the-python-cli.md
JavaScript CLI のドキュメントページ（tg-cli）	introduction-to-tg-cli-javascript.md
OpenClaw 自動化ツール（一般、Docker Compose、DigitalOcean）	openclaw.md、openclaw-docker-compose.md、openclaw-digitalocean.md
CI/CD パイプラインのパターン（ドキュメントページ）	example-cicd-configurations.md
CI ランナー用 GitHub Action — Service Key を使用してランナーに Client をインストールし、ワークフローのステップから IP 制限された／プライベートなリソースにアクセスできるようにします	gh-twingate-github-action.md
AWS タグ駆動のリソース自動化（EC2、ECS、RDS の tg_resource／tg_groups タグ → Lambda が EventBridge／CloudWatch Events 経由で Twingate リソースを作成／削除）	gh-twingate-labs-tg-aws-tag-sync.md
Deno／TypeScript 管理 CLI（tg-cli）— トポロジーを Excel／PNG にエクスポート（GraphViz）、グループ／ネットワーク／リソースをインポート	gh-twingate-labs-tg-cli.md
Python CLI 用ブラウザー Web UI（tgcli-web）— tgcli ライブラリをラップする FastAPI アプリ。エンティティの閲覧、差分レビュー付きのエクスポート／インポート、ヘルスダッシュボード、Docker／K8s／pip によるインストール	gh-twingate-labs-tgcli-web-py.md
GraphQL API の初心者向け Jupyter／Python チュートリアル — クエリ、ミューテーション、イントロスペクションを扱い、GraphQL の事前知識は不要です	gh-twingate-labs-twingate-api-intro-with-python.md
Python 管理 CLI（Typer ベースの tgcli）— リモートネットワーク／リソース／コネクター／グループ／ユーザー／サービスアカウントの完全な CRUD、マルチテナントセッション、Synced から Manual へのグループ移行	gh-twingate-labs-twingate-cli.md
一般的な運用スクリプト（クライアントのデプロイ、Intune／Autopilot、ゲートウェイを DNS サーバーとして使用する方法、Network Events の CSV フィルタリング、グループの一括削除）— LLM を活用した参考例であり、サポート対象の製品ではありません	gh-twingate-solutions-general-scripts.md
ネットワークの健全性／インサイトレポート生成ツール — Network Events のエクスポートをリソース／ユーザー／コネクター／リモートネットワークの健全性分析に変換する Jupyter ノートブック	gh-twingate-solutions-health-report-generator.md

この表はすばやく参照するためのものであり、コーパス全体を網羅しているわけではありません。質問がどの行にも当てはまらない場合は、回答する前に references/ を grep してください。まずスキーマを確認してください。クエリやミューテーションを記憶だけで書いてはいけません。フィールド名と列挙値は変更されることがあります。