コンテンツにスキップ
AegisMesh ドキュメント

★ Fork独自拡張APIリファレンス

本ページでは、オリジナルNetBirdに対して追加された AegisMesh 専用の拡張REST APIエンドポイント の仕様を解説します。

1. エンタープライズ信頼ルート証明書管理 API (Certificates)

社内 UTM の SSL インスペクション用 CA 証明書の登録、グループ別配信、および iOS 向け .mobileconfig プロファイルダウンロードを提供します。

1.1 証明書一覧取得

  • Endpoint: GET /api/certificates
  • 認証: 管理者またはユーザー Bearer トークン
  • Response (200 OK): 
    [
      {
        "id": "cert-c4v9x10",
        "label": "FortiGate Corporate SSL Inspection Root CA",
        "sha256_fingerprint": "a1b2c3d4e5f6...",
        "not_before": "2026-01-01T00:00:00Z",
        "not_after": "2036-01-01T00:00:00Z",
        "target_groups": ["group-corporate-machines"],
        "created_at": "2026-10-24T12:00:00Z",
        "updated_at": "2026-10-24T12:00:00Z"
      }
    ]

1.2 証明書新規登録

  • Endpoint: POST /api/certificates
  • 権限: AdminPower 必須
  • Request Body: 
    {
      "label": "FortiGate SSL Inspection Root CA",
      "cert_pem": "-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIU...\n-----END CERTIFICATE-----",
      "target_groups": ["group-corporate-machines"]
    }
  • Response (201 Created): 登録された CertificateResponse オブジェクトを返却。

1.3 証明書削除 (クライアントからの即時自動パージ)

  • Endpoint: DELETE /api/certificates/{id}
  • 権限: AdminPower 必須
  • Response: 200 OK ({"message": "certificate deleted successfully"})
  • 挙動: 接続中の全クライアント端末の OS ルートストアから該当証明書が即座にアンインストールされます。

1.4 Apple 構成プロファイル生成・ダウンロード (.mobileconfig)

  • Endpoint: GET /api/certificates/{id}/mobileconfig
  • Content-Type: application/x-apple-aspen-config
  • 説明: iOS / iPadOS / macOS 端末でワンタップでインポートできる Apple 署名規格プロファイルを動的生成します。

2. テナント作成 & プロビジョニング API

新規組織・顧客テナントを作成し、ホストOS上に専用の特権TUNクライアントコンテナを自動デプロイします。

  • Endpoint: POST /api/v1/admin/tenants
  • 認証: 管理者パーソナルアクセストークン（Bearer）

Request Body

{
  "name": "株式会社草クラウド",
  "slug": "kusa-cloud-tenant",
  "disable_masquerade": true,
  "max_peers": 100,
  "enforce_exit_node": true,
  "primary_reseller_id": "reseller-1234"
}

Response (201 Created)

{
  "id": "tenant-abcd-5678",
  "name": "株式会社草クラウド",
  "slug": "kusa-cloud-tenant",
  "container_id": "nb-client-tenant-kusa-cloud-tenant",
  "container_status": "running",
  "initial_setup_key": "9A8B7C6D-5E4F-3A2B-1C0D-...",
  "created_at": "2026-09-29T11:30:00Z"
}

3. テナント削除 API

指定したテナントのアカウントデータと、ホスト上の特権コンテナを完全に停止・破棄します。

  • Endpoint: DELETE /api/v1/admin/tenants/{id}
  • Response: 204 No Content

4. 従量課金 ＆ リセラー移管 API (Billing Engine)

4.1 月次請求サマリーレポート

  • Endpoint: GET /api/admin/billing/reports?month=YYYY-MM
  • 権限: SuperAdmin または ResaleAdmin
  • 説明: 各テナントの日次ピーク接続数（High-Water Mark）から算出された月次請求額とリセラー粗利益を返却。

4.2 テナント個別課金設定更新

  • Endpoint: PUT /api/admin/tenants/{id}/billing
  • Request Body: 
    {
      "billing_model": "user",
      "user_unit_price": 500,
      "peer_unit_price": 200,
      "billing_timezone": "Asia/Tokyo"
    }

4.3 翌月1日リセラー移管予約 (Model B)

  • Endpoint: POST /api/admin/tenants/{id}/transfer
  • Request Body: {"new_reseller_id": "reseller-target-01"}
  • 説明: 即時移管に伴う請求トラブルを防ぐため、翌月1日 00:00:00 UTC に自動適用される予約を登録。
  • 予約キャンセル: DELETE /api/admin/tenants/{id}/transfer

5. テナントリソースクォータ API (Resource Quotas)

特定テナントのリソース使用状況と上限設定を照会・検証します。

  • Endpoint: GET /api/account/quota (自テナント用) / GET /api/admin/tenants/{id}/quota (管理者用)
  • Response (200 OK): 
    {
      "peers_used": 28,
      "quota_max_peers": 50,
      "routes_used": 5,
      "quota_max_routes": 100,
      "setup_keys_used": 4,
      "quota_max_setup_keys": 20,
      "users_used": 12,
      "quota_max_users": 20
    }

6. 独自リレーサーバー管理 API (Relays & Governance)

  • 自己登録 (HMAC): POST /api/relays/register (ヘッダー X-Relay-Signature)
  • 死活監視: PUT /api/relays/{id}/heartbeat (SessionToken 認証、1分周期)
  • 承認ガバナンス: POST /api/relays/{id}/approve (SuperAdmin 承認、配信リスト追加)
  • 拒絶・遮断: POST /api/relays/{id}/reject (SuperAdmin 拒絶)

7. エッジ負荷ハートビート API

各分散エッジ拠点（Signal / Relay / coturn）から1分周期で負荷情報を収集し、クライアントへの最適ルーティングに反映します。

  • Endpoint: POST /api/internal/edges/heartbeat
  • 認証: エッジ共有内部シークレット（Header: X-Edge-Secret）

Request Body

{
  "edge_id": "edge-tokyo-01",
  "region": "ap-northeast-1",
  "public_ip": "203.0.113.50",
  "cpu_usage_pct": 14.2,
  "active_tunnels": 128,
  "network_egress_mbps": 45.8,
  "timestamp": 1790685600
}

Response (200 OK)

{
  "status": "healthy",
  "registered_peers_count": 128,
  "next_heartbeat_seconds": 60
}

直近3分間（180秒）ハートビートが届かないエッジは、データベース上で自動的にフェイルオーバー（Soft Inactive）され、クライアントへの配信対象から除外されます。