From c2c07290b06652a096b1d81422122eb767586a60 Mon Sep 17 00:00:00 2001
From: Alexander Mattoni <5110855+mattoni@users.noreply.github.com>
Date: Thu, 2 Jul 2026 17:58:03 +0000
Subject: [PATCH 1/2] Add internal API scoping mechanism and descriptions

---
 .redocly.yaml                                 | 10 +++
 .../containers/config/ContainerRuntime.yml    |  2 +
 .../config/runtime/RuntimeInternalApi.yml     | 17 +++++
 internal/api.yml                              | 14 +---
 internal/paths/conductor/tasks.yml            | 25 -------
 internal/paths/container/certificates.yml     |  7 +-
 internal/paths/container/container.yml        |  7 +-
 internal/paths/container/domains.yml          |  7 +-
 internal/paths/container/instances.yml        |  7 +-
 internal/paths/environment/containers.yml     |  7 +-
 internal/paths/environment/environment.yml    |  4 ++
 internal/paths/environment/instances.yml      |  7 +-
 internal/paths/environment/ips.yml            |  7 +-
 internal/paths/environment/lbtelemetry.yml    |  7 +-
 .../paths/environment/scoped-variables.yml    |  4 ++
 internal/paths/environment/services.yml       |  7 +-
 .../paths/environment/virtual-machines.yml    |  6 +-
 internal/paths/ha/checkin.yml                 |  3 +
 internal/paths/hub/hub.yml                    |  6 +-
 internal/paths/hub/integration.yml            |  3 +
 internal/paths/hub/notifications.yml          |  4 +-
 internal/paths/monitoring/events.yml          |  3 +
 internal/paths/monitoring/metrics.yml         |  3 +
 internal/paths/object-cache/object-cache.yml  | 16 +++++
 internal/paths/sdn/environments.yml           |  7 +-
 internal/paths/sdn/instances.yml              |  7 +-
 internal/paths/sdn/networks.yml               |  7 +-
 internal/paths/server/containers.yml          |  7 +-
 internal/paths/server/external-volumes.yml    | 28 ++++++++
 internal/paths/server/image-download.yml      |  7 +-
 internal/paths/server/images.yml              |  7 +-
 internal/paths/server/instance-telemetry.yml  | 38 -----------
 internal/paths/server/instances.yml           |  7 +-
 internal/paths/server/poweroff.yml            |  5 +-
 internal/paths/server/reboot.yml              |  5 +-
 internal/paths/server/server.yml              |  7 +-
 internal/paths/virtual-machine/domains.yml    |  4 ++
 internal/paths/virtual-machine/gateways.yml   | 65 -------------------
 .../paths/virtual-machine/virtual-machine.yml |  8 ++-
 internal/paths/vpn/login.yml                  | 42 ------------
 .../StackSpecContainerConfigRuntime.yml       |  5 ++
 .../runtime/StackSpecRuntimeInternalApi.yml   | 18 +++++
 42 files changed, 249 insertions(+), 208 deletions(-)
 create mode 100644 components/schemas/containers/config/runtime/RuntimeInternalApi.yml
 delete mode 100644 internal/paths/conductor/tasks.yml
 create mode 100644 internal/paths/server/external-volumes.yml
 delete mode 100644 internal/paths/server/instance-telemetry.yml
 delete mode 100644 internal/paths/virtual-machine/gateways.yml
 delete mode 100644 internal/paths/vpn/login.yml
 create mode 100644 stackspec/schema/runtime/StackSpecRuntimeInternalApi.yml

diff --git a/.redocly.yaml b/.redocly.yaml
index ce4d48bd..29ed5d38 100644
--- a/.redocly.yaml
+++ b/.redocly.yaml
@@ -4,6 +4,16 @@ apis:
     root: ./platform/api.yml
   cycle-internal-api:
     root: ./internal/api.yml
+    rules:
+      rule/require-scopes:
+        subject:
+          type: Operation
+          property: x-cycle-scopes
+        assertions:
+          defined: true
+          nonEmpty: true
+        message: Internal API operations must declare x-cycle-scopes.
+        severity: error
   cycle-scheduler-api:
     root: ./scheduler/api.yml
   cycle-ial:
diff --git a/components/schemas/containers/config/ContainerRuntime.yml b/components/schemas/containers/config/ContainerRuntime.yml
index d54f716c..5e809582 100644
--- a/components/schemas/containers/config/ContainerRuntime.yml
+++ b/components/schemas/containers/config/ContainerRuntime.yml
@@ -85,6 +85,8 @@ properties:
         - CAP_LEASE
         - CAP_WAKE_ALARM
     description: A list of linux kernel capabilites for the given container.
+  internal_api:
+    $ref: ./runtime/RuntimeInternalApi.yml
   workdir:
     type: string
     description: Configure the working directory for the given container.
diff --git a/components/schemas/containers/config/runtime/RuntimeInternalApi.yml b/components/schemas/containers/config/runtime/RuntimeInternalApi.yml
new file mode 100644
index 00000000..321ee599
--- /dev/null
+++ b/components/schemas/containers/config/runtime/RuntimeInternalApi.yml
@@ -0,0 +1,17 @@
+title: RuntimeInternalApi
+description: Configuration options for the internal API access within instances of this container.
+type: object
+properties:
+  scope:
+    oneOf:
+      - type: array
+        description: Scopes determine which set of endpoints instances of this container can reach over the internal API.
+        items:
+          type: string
+          enum:
+            - "self"
+            - "environment"
+            - "networks"
+            - "server"
+            - "notifications"
+      - type: "null"
diff --git a/internal/api.yml b/internal/api.yml
index 13b5c5c3..d9f4e824 100644
--- a/internal/api.yml
+++ b/internal/api.yml
@@ -57,8 +57,8 @@ paths:
     $ref: paths/server/server.yml
   /v1/server/instances:
     $ref: paths/server/instances.yml
-  /v1/server/instances/telemetry:
-    $ref: paths/server/instance-telemetry.yml
+  /v1/server/external-volumes:
+    $ref: paths/server/external-volumes.yml
   /v1/server/containers:
     $ref: paths/server/containers.yml
   /v1/server/images:
@@ -80,10 +80,6 @@ paths:
   /v1/containers/domains:
     $ref: paths/container/domains.yml
 
-  # Conductor
-  /v1/conductor/tasks:
-    $ref: paths/conductor/tasks.yml
-
   # HA
   /v1/ha/checkin:
     $ref: paths/ha/checkin.yml
@@ -94,10 +90,6 @@ paths:
   /v1/monitoring/events:
     $ref: paths/monitoring/events.yml
 
-  # VPN
-  /v1/vpn/login:
-    $ref: paths/vpn/login.yml
-
   # SDN
   /v1/sdn/networks:
     $ref: paths/sdn/networks.yml
@@ -111,8 +103,6 @@ paths:
     $ref: paths/virtual-machine/virtual-machine.yml
   /v1/virtual-machine/domains:
     $ref: paths/virtual-machine/domains.yml
-  /v1/virtual-machine/gateways:
-    $ref: paths/virtual-machine/gateways.yml
 
   # Object Cache
   /v1/object-cache:
diff --git a/internal/paths/conductor/tasks.yml b/internal/paths/conductor/tasks.yml
deleted file mode 100644
index 47425151..00000000
--- a/internal/paths/conductor/tasks.yml
+++ /dev/null
@@ -1,25 +0,0 @@
-post:
-  operationId: "createInstanceJob"
-  summary: Create Instance Job
-  description: |
-    Used to perform different actions on a given instance.
-  tags:
-    - Containers
-    - Instances
-  parameters: []
-  requestBody:
-    required: true
-    content:
-      application/json:
-        schema:
-          $ref: ../../components/instances/task/InstanceTask.yml
-  responses:
-    default:
-      $ref: ../../../components/responses/errors/DefaultError.yml
-    200:
-      description: Returns nothing on success.
-      content:
-        application/json:
-          schema:
-            type: object
-            additionalProperties: false
diff --git a/internal/paths/container/certificates.yml b/internal/paths/container/certificates.yml
index b94d7ae3..ae508fc1 100644
--- a/internal/paths/container/certificates.yml
+++ b/internal/paths/container/certificates.yml
@@ -1,9 +1,14 @@
 get:
   operationId: "getContainerCertificates"
   summary: List Container Certificates
-  description: Get the TLS certificates associated with the domains pointed at this container.
+  description: |
+    Get the TLS certificates associated with the domains pointed at this container.
+
+    Requires the `self` scope to be set on the container runtime config.
   tags:
     - Containers
+  x-cycle-scopes:
+    - self
   parameters:
     - name: container-id
       in: query
diff --git a/internal/paths/container/container.yml b/internal/paths/container/container.yml
index b19057fd..96492003 100644
--- a/internal/paths/container/container.yml
+++ b/internal/paths/container/container.yml
@@ -1,9 +1,14 @@
 get:
   operationId: "getContainer"
   summary: Get Container
-  description: Gets a container. By default will grab the container of this instance, but a `container-id`` parameter can be passed to grab any other container in the same environment.
+  description: |
+    Gets a container. By default will grab the container of this instance, but a `container-id`` parameter can be passed to grab any other container in the same environment.
+
+    Requires the `self` scope to be set on the container runtime config.
   tags:
     - Containers
+  x-cycle-scopes:
+    - self
   parameters:
     - name: container-id
       in: query
diff --git a/internal/paths/container/domains.yml b/internal/paths/container/domains.yml
index 656fae4b..e942991b 100644
--- a/internal/paths/container/domains.yml
+++ b/internal/paths/container/domains.yml
@@ -1,9 +1,14 @@
 get:
   operationId: "getContainerDomains"
   summary: List Container Domains
-  description: Get the domains pointed at a container.
+  description: |
+    Get the domains pointed at a container.
+
+    Requires the `self` scope to be set on the container runtime config.
   tags:
     - Containers
+  x-cycle-scopes:
+    - self
   parameters:
     - name: container-id
       in: query
diff --git a/internal/paths/container/instances.yml b/internal/paths/container/instances.yml
index cb02bdd5..b5964a83 100644
--- a/internal/paths/container/instances.yml
+++ b/internal/paths/container/instances.yml
@@ -1,10 +1,15 @@
 get:
   operationId: "getContainerInstances"
   summary: Get Container Instances
-  description: Gets the instances of a container. By default will grab the instances of the same container, but a `container-id`` parameter can be passed to grab any other container instances in the same environment.
+  description: |
+    Gets the instances of a container. By default will grab the instances of the same container, but a `container-id`` parameter can be passed to grab any other container instances in the same environment.
+
+    Requires the `self` scope to be set on the container runtime config.
   tags:
     - Containers
     - Instances
+  x-cycle-scopes:
+    - self
   parameters:
     - name: container-id
       in: query
diff --git a/internal/paths/environment/containers.yml b/internal/paths/environment/containers.yml
index c6fe4570..58d568c1 100644
--- a/internal/paths/environment/containers.yml
+++ b/internal/paths/environment/containers.yml
@@ -1,9 +1,14 @@
 get:
   operationId: "getEnvironmentContainers"
   summary: List Environment Containers
-  description: Lists all Containers that are part of the same Environment as this Instance.
+  description: |
+    Lists all Containers that are part of the same Environment as this Instance.
+
+    Requires the `environment` scope to be set on the container runtime config.
   tags:
     - Environments
+  x-cycle-scopes:
+    - environment
   parameters: []
   responses:
     default:
diff --git a/internal/paths/environment/environment.yml b/internal/paths/environment/environment.yml
index 6feefbc8..2f066b3a 100644
--- a/internal/paths/environment/environment.yml
+++ b/internal/paths/environment/environment.yml
@@ -3,8 +3,12 @@ get:
   summary: Get Environment
   description: |
     Gets the Environment that this instance is a part of.
+
+    Requires the `environment` scope to be set on the container runtime config.
   tags:
     - Environments
+  x-cycle-scopes:
+    - environment
   parameters: []
   responses:
     default:
diff --git a/internal/paths/environment/instances.yml b/internal/paths/environment/instances.yml
index 3147d77d..3b2e6b1a 100644
--- a/internal/paths/environment/instances.yml
+++ b/internal/paths/environment/instances.yml
@@ -1,10 +1,15 @@
 get:
   operationId: "getEnvironmentInstances"
   summary: List Environment Instances
-  description: Lists all instances present in this instance's environment.
+  description: |
+    Lists all instances present in this instance's environment.
+
+    Requires the `environment` scope to be set on the container runtime config.
   tags:
     - Environments
     - Instances
+  x-cycle-scopes:
+    - environment
   parameters: []
   responses:
     default:
diff --git a/internal/paths/environment/ips.yml b/internal/paths/environment/ips.yml
index 7e79fd2e..d9d72f39 100644
--- a/internal/paths/environment/ips.yml
+++ b/internal/paths/environment/ips.yml
@@ -1,9 +1,14 @@
 get:
   operationId: "getEnvironmentIPs"
   summary: List Environment IPs
-  description: Lists the IPs associated with this Instance's Environment.
+  description: |
+    Lists the IPs associated with this Instance's Environment.
+
+    Requires the `environment` scope to be set on the container runtime config.
   tags:
     - Environments
+  x-cycle-scopes:
+    - environment
   parameters: []
   responses:
     default:
diff --git a/internal/paths/environment/lbtelemetry.yml b/internal/paths/environment/lbtelemetry.yml
index 316d98e1..da35cd32 100644
--- a/internal/paths/environment/lbtelemetry.yml
+++ b/internal/paths/environment/lbtelemetry.yml
@@ -1,9 +1,14 @@
 post:
   operationId: "submitLoadBalancerTelemetry"
   summary: Submit Environment Load Balancer Telemetry
-  description: Submit load balancer telemetry data.
+  description: |
+    Submit load balancer telemetry data.
+
+    Requires the `environment` scope to be set on the container runtime config.
   tags:
     - Environments
+  x-cycle-scopes:
+    - environment
   parameters: []
   requestBody:
     required: true
diff --git a/internal/paths/environment/scoped-variables.yml b/internal/paths/environment/scoped-variables.yml
index bbb366ee..e7559c61 100644
--- a/internal/paths/environment/scoped-variables.yml
+++ b/internal/paths/environment/scoped-variables.yml
@@ -3,8 +3,12 @@ get:
   summary: Get Environment Scoped Variables
   description: |
     Gets the scoped variables that are accessible to this instance via internal API.
+
+    Requires the `environment` scope to be set on the container runtime config.
   tags:
     - Scoped Variables
+  x-cycle-scopes:
+    - environment
   parameters: []
   responses:
     default:
diff --git a/internal/paths/environment/services.yml b/internal/paths/environment/services.yml
index 8d1bb8f4..0f3206fa 100644
--- a/internal/paths/environment/services.yml
+++ b/internal/paths/environment/services.yml
@@ -1,9 +1,14 @@
 get:
   operationId: "getEnvironmentServices"
   summary: List Environment Services
-  description: Lists the services containers/instances that are in the same environment as this instance.
+  description: |
+    Lists the services containers/instances that are in the same environment as this instance.
+
+    Requires the `environment` scope to be set on the container runtime config.
   tags:
     - Environments
+  x-cycle-scopes:
+    - environment
   parameters: []
   responses:
     default:
diff --git a/internal/paths/environment/virtual-machines.yml b/internal/paths/environment/virtual-machines.yml
index 52a42d10..f51d9259 100644
--- a/internal/paths/environment/virtual-machines.yml
+++ b/internal/paths/environment/virtual-machines.yml
@@ -2,9 +2,13 @@ get:
   operationId: "getEnvironmentVirtualMachines"
   summary: Get Environment Virtual Machines
   description: |
-     Returns a list of virtual machines that are in the same environment as this instance.
+    Returns a list of virtual machines that are in the same environment as this instance.
+
+    Requires the `environment` scope to be set on the container runtime config.
   tags:
     - Environments
+  x-cycle-scopes:
+    - environment
   parameters: []
   responses:
     default:
diff --git a/internal/paths/ha/checkin.yml b/internal/paths/ha/checkin.yml
index ffe6b2b8..f4c3ec93 100644
--- a/internal/paths/ha/checkin.yml
+++ b/internal/paths/ha/checkin.yml
@@ -4,8 +4,11 @@ post:
   description: |
     Hit this endpoint every 30 seconds to check in and have the platform select and maintain a primary instance.
     Every instance you wish to be considered for a primary should hit this endpoint roughly every 30 seconds. The platform will choose one instance as the primary, and it will continue to be the primary until it stops checking in. If a primary stops checking in, a secondary will be selected to be promoted to primary.
+
+    Does not require a scope, but `config.deploy.ha_elections` must be enabled on this container to access this endpoint.
   tags:
     - High Availability
+  x-cycle-scopes:
   requestBody:
     required: true
     content:
diff --git a/internal/paths/hub/hub.yml b/internal/paths/hub/hub.yml
index 5d538228..7ac942b2 100644
--- a/internal/paths/hub/hub.yml
+++ b/internal/paths/hub/hub.yml
@@ -1,10 +1,14 @@
 get:
   operationId: "getHub"
   summary: Get Hub
-  description: Gets the hub that this instance is a member of.
+  description: |
+    Gets the hub that this instance is a member of.
+
+    Does not require a scope
   tags:
     - Hubs
   parameters: []
+  x-cycle-scopes:
   responses:
     default:
       $ref: ../../../components/responses/errors/DefaultError.yml
diff --git a/internal/paths/hub/integration.yml b/internal/paths/hub/integration.yml
index c44b2fd5..f73fd478 100644
--- a/internal/paths/hub/integration.yml
+++ b/internal/paths/hub/integration.yml
@@ -3,8 +3,11 @@ get:
   summary: Get Hub Integration
   description: |
     Gets an integration based on a provided identifier or vendor query parameter. At least one of these must be provided.
+
+    Only internal Cycle services can access this endpoint at this time.
   tags:
     - Hubs
+  x-cycle-scopes:
   parameters:
     - name: identifier
       in: query
diff --git a/internal/paths/hub/notifications.yml b/internal/paths/hub/notifications.yml
index a9bcbec3..fcaf17da 100644
--- a/internal/paths/hub/notifications.yml
+++ b/internal/paths/hub/notifications.yml
@@ -13,7 +13,9 @@ get:
     Requesting this endpoint without a `?token=<token>` URL parameter will result in receiving a short lived token in the response body. That 
     token can then be applied to the URL parameter to the same endpoint to upgrade the connection to a websocket.
 
-    Requires the `hubs-notifications-listen` capability.
+    Requires the `notifications` scope to be set on the container runtime config.
+  x-cycle-scopes:
+    - notifications
   responses:
     200:
       description: Returns the credentials necessary for upgrading this connection into a web socket.
diff --git a/internal/paths/monitoring/events.yml b/internal/paths/monitoring/events.yml
index af2f0a20..45eb5631 100644
--- a/internal/paths/monitoring/events.yml
+++ b/internal/paths/monitoring/events.yml
@@ -3,8 +3,11 @@ post:
   summary: Post Event
   description: |
     Post a custom event to Cycle's monitoring system.
+
+    Does not require a scope.
   tags:
     - Monitoring
+  x-cycle-scopes:
   parameters: []
   requestBody:
     required: true
diff --git a/internal/paths/monitoring/metrics.yml b/internal/paths/monitoring/metrics.yml
index f258d20c..3768f5fe 100644
--- a/internal/paths/monitoring/metrics.yml
+++ b/internal/paths/monitoring/metrics.yml
@@ -3,8 +3,11 @@ post:
   summary: Post Metric
   description: |
     Post data to Cycle's monitoring system.
+
+    Does not require a scope.
   tags:
     - Monitoring
+  x-cycle-scopes:
   parameters: []
   requestBody:
     required: true
diff --git a/internal/paths/object-cache/object-cache.yml b/internal/paths/object-cache/object-cache.yml
index 17175012..d1c0239e 100644
--- a/internal/paths/object-cache/object-cache.yml
+++ b/internal/paths/object-cache/object-cache.yml
@@ -3,8 +3,16 @@ get:
   summary: Get Object Cache
   description: |
     Returns an object saved to the internal object cache.
+
+    Requires the `server` scope to be set on the container runtime config if using the `global` cache.
+    Requires the `environment` scope to be set on the container runtime config if using the `environment` cache.
+    Requires the `self` scope to be set on the container runtime config if using the `container` or `instance` cache.
   tags:
     - Object Cache
+  x-cycle-scopes:
+    - server
+    - environment
+    - self
   parameters:
     - name: scope
       in: query
@@ -43,9 +51,17 @@ post:
   summary: Post Object Cache
   description: |
     Save an item to the internal API object cache.
+
+    Requires the `server` scope to be set on the container runtime config if using the `global` cache.
+    Requires the `environment` scope to be set on the container runtime config if using the `environment` cache.
+    Requires the `self` scope to be set on the container runtime config if using the `container` or `instance` cache.
   tags:
     - Object Cache
   parameters: []
+  x-cycle-scopes:
+    - server
+    - environment
+    - self
   requestBody:
     required: true
     content:
diff --git a/internal/paths/sdn/environments.yml b/internal/paths/sdn/environments.yml
index f80c3b8b..c4d6dd28 100644
--- a/internal/paths/sdn/environments.yml
+++ b/internal/paths/sdn/environments.yml
@@ -1,11 +1,16 @@
 get:
   operationId: "getNetworkEnvironments"
   summary: List Network Environments
-  description: Lists all environments present in this instance's SDN networks.
+  description: |
+    Lists all environments present in this instance's SDN networks.
+
+    Requires the `networks` scope to be set on the container runtime config.
   tags:
     - SDN
     - Environments
   parameters: []
+  x-cycle-scopes:
+    - networks
   responses:
     default:
       $ref: ../../../components/responses/errors/DefaultError.yml
diff --git a/internal/paths/sdn/instances.yml b/internal/paths/sdn/instances.yml
index aa2c6db6..b1d14a95 100644
--- a/internal/paths/sdn/instances.yml
+++ b/internal/paths/sdn/instances.yml
@@ -1,11 +1,16 @@
 get:
   operationId: "getNetworkInstances"
   summary: List Network Instances
-  description: Lists all instances present in this instance's SDN networks.
+  description: |
+    Lists all instances present in this instance's SDN networks.
+
+    Requires the `networks` scope to be set on the container runtime config.
   tags:
     - SDN
     - Instances
   parameters: []
+  x-cycle-scopes:
+    - networks
   responses:
     default:
       $ref: ../../../components/responses/errors/DefaultError.yml
diff --git a/internal/paths/sdn/networks.yml b/internal/paths/sdn/networks.yml
index 0eb2f3d2..8d59daab 100644
--- a/internal/paths/sdn/networks.yml
+++ b/internal/paths/sdn/networks.yml
@@ -1,10 +1,15 @@
 get:
   operationId: "getNetworks"
   summary: List Networks
-  description: Lists all networks attached to this instance.
+  description: |
+    Lists all networks attached to this instance.
+
+    Requires the `networks` scope to be set on the container runtime config.
   tags:
     - SDN
   parameters: []
+  x-cycle-scopes:
+    - networks
   responses:
     default:
       $ref: ../../../components/responses/errors/DefaultError.yml
diff --git a/internal/paths/server/containers.yml b/internal/paths/server/containers.yml
index d6bb1d8f..08b90424 100644
--- a/internal/paths/server/containers.yml
+++ b/internal/paths/server/containers.yml
@@ -4,8 +4,13 @@ get:
     - Servers
     - Containers
   parameters: []
+  x-cycle-scopes:
+    - server
   summary: List Server Containers
-  description: Lists all containers present on the same server as this instance.
+  description: |
+    Lists all containers present on the same server as this instance.
+
+    Requires the `server` scope to be set on the container runtime config.
   responses:
     default:
       $ref: ../../../components/responses/errors/DefaultError.yml
diff --git a/internal/paths/server/external-volumes.yml b/internal/paths/server/external-volumes.yml
new file mode 100644
index 00000000..60b07024
--- /dev/null
+++ b/internal/paths/server/external-volumes.yml
@@ -0,0 +1,28 @@
+get:
+  operationId: "getServerExternalVolumes"
+  summary: List Server External Volumes
+  description: |
+    Lists all external volumes connected to this server.
+
+    Requires the `server` scope to be set on the container runtime config.
+  tags:
+    - Servers
+  parameters: []
+  x-cycle-scopes:
+    - server
+  responses:
+    default:
+      $ref: ../../../components/responses/errors/DefaultError.yml
+    200:
+      description: Returns a list of external volumes.
+      content:
+        application/json:
+          schema:
+            type: object
+            required:
+              - data
+            properties:
+              data:
+                type: array
+                items:
+                  "$ref": "../../../components/schemas/infrastructure/external-volumes/ExternalVolume.yml"
diff --git a/internal/paths/server/image-download.yml b/internal/paths/server/image-download.yml
index ff371417..fd5a3c79 100644
--- a/internal/paths/server/image-download.yml
+++ b/internal/paths/server/image-download.yml
@@ -1,11 +1,16 @@
 post:
   operationId: "downloadImage"
   summary: Download Image
-  description: Downloads the specified image to the server.
+  description: |
+    Downloads the specified image to the server.
+
+    Requires the `server` scope to be set on the container runtime config.
   tags:
     - Servers
     - Images
   parameters: []
+  x-cycle-scopes:
+    - server
   requestBody:
     required: true
     content:
diff --git a/internal/paths/server/images.yml b/internal/paths/server/images.yml
index 6af334a5..8f937f11 100644
--- a/internal/paths/server/images.yml
+++ b/internal/paths/server/images.yml
@@ -1,11 +1,16 @@
 get:
   operationId: "getServerImages"
   summary: List Server Images
-  description: Lists all images downloaded onto the server this instance is on.
+  description: |
+    Lists all images downloaded onto the server this instance is on.
+
+    Requires the `server` scope to be set on the container runtime config.
   tags:
     - Servers
     - Containers
   parameters: []
+  x-cycle-scopes:
+    - server
   responses:
     default:
       $ref: ../../../components/responses/errors/DefaultError.yml
diff --git a/internal/paths/server/instance-telemetry.yml b/internal/paths/server/instance-telemetry.yml
deleted file mode 100644
index 78c78fc1..00000000
--- a/internal/paths/server/instance-telemetry.yml
+++ /dev/null
@@ -1,38 +0,0 @@
-get:
-  operationId: "getServerInstancesTelemetry"
-  summary: Get Server Instances Telemetry
-  description: Gets resource telemetry for this instance.
-  tags:
-    - Servers
-    - Instances
-  parameters: []
-  responses:
-    default:
-      $ref: ../../../components/responses/errors/DefaultError.yml
-    200:
-      description: Returns a list of resource telemetry snapshots.
-      content:
-        application/json:
-          schema:
-            type: object
-            required:
-              - data
-            properties:
-              data:
-                type: array
-                items:
-                  type: object
-                  required:
-                    - instance_id
-                    - container_id
-                    - environment_id
-                    - stats
-                  properties:
-                    instance_id:
-                      $ref: ../../../components/schemas/ID.yml
-                    container_id:
-                      $ref: ../../../components/schemas/ID.yml
-                    environment_id:
-                      $ref: ../../../components/schemas/ID.yml
-                    stats:
-                      $ref: "../../../components/schemas/containers/instances/snapshots/ResourceSnapshot.yml"
diff --git a/internal/paths/server/instances.yml b/internal/paths/server/instances.yml
index ba4351bc..2f5666a5 100644
--- a/internal/paths/server/instances.yml
+++ b/internal/paths/server/instances.yml
@@ -1,11 +1,16 @@
 get:
   operationId: "getServerInstances"
   summary: Get Server Instances
-  description: Gets a list of instances that are on the same server as this instance.
+  description: |
+    Gets a list of instances that are on the same server as this instance.
+
+    Requires the `server` scope to be set on the container runtime config.
   tags:
     - Servers
     - Instances
   parameters: []
+  x-cycle-scopes:
+    - server
   responses:
     default:
       $ref: ../../../components/responses/errors/DefaultError.yml
diff --git a/internal/paths/server/poweroff.yml b/internal/paths/server/poweroff.yml
index e6482470..1ae58392 100644
--- a/internal/paths/server/poweroff.yml
+++ b/internal/paths/server/poweroff.yml
@@ -3,10 +3,12 @@ post:
   summary: Power Off Server
   description: |
     Initiates a graceful poweroff on the host server this instance is running on.
-    The container must have `config.runtime.host.power_management` set to true to utilize this endpoint.
+
+    Does not require a scope, but the container must have `config.runtime.host.power_management` set to true to utilize this endpoint.
   tags:
     - Servers
   parameters: []
+  x-cycle-scopes:
   responses:
     default:
       $ref: ../../../components/responses/errors/DefaultError.yml
@@ -21,4 +23,3 @@ post:
             properties:
               data:
                 type: boolean
-                
diff --git a/internal/paths/server/reboot.yml b/internal/paths/server/reboot.yml
index 8c9e0924..da7f5d49 100644
--- a/internal/paths/server/reboot.yml
+++ b/internal/paths/server/reboot.yml
@@ -3,10 +3,12 @@ post:
   summary: Reboot Server
   description: |
     Initiates a graceful reboot on the host server this instance is running on. 
-    The container must have `config.runtime.host.power_management` set to true to utilize this endpoint.
+
+    Does not require a scope, but the container must have `config.runtime.host.power_management` set to true to utilize this endpoint.
   tags:
     - Servers
   parameters: []
+  x-cycle-scopes:
   responses:
     default:
       $ref: ../../../components/responses/errors/DefaultError.yml
@@ -21,4 +23,3 @@ post:
             properties:
               data:
                 type: boolean
-                
diff --git a/internal/paths/server/server.yml b/internal/paths/server/server.yml
index 24dadfcd..c3bc756d 100644
--- a/internal/paths/server/server.yml
+++ b/internal/paths/server/server.yml
@@ -4,7 +4,12 @@ get:
     - Servers
   parameters: []
   summary: Get Server
-  description: Gets the server this instance is running on.
+  description: |
+    Gets the server this instance is running on.
+
+    Requires the `server` scope to be set on the container runtime config.
+  x-cycle-scopes:
+    - server
   responses:
     default:
       $ref: ../../../components/responses/errors/DefaultError.yml
diff --git a/internal/paths/virtual-machine/domains.yml b/internal/paths/virtual-machine/domains.yml
index 23c58351..1fbc7a9d 100644
--- a/internal/paths/virtual-machine/domains.yml
+++ b/internal/paths/virtual-machine/domains.yml
@@ -3,8 +3,12 @@ get:
   summary: Get Virtual Machine Domains
   description: |
     Returns the domains associated with the specified virtual machine.
+
+    Requires the `environment` scope to be set on the container runtime config.
   tags:
     - Virtual Machines
+  x-cycle-scopes:
+    - environment
   parameters:
     - name: virtual-machine-id
       in: query
diff --git a/internal/paths/virtual-machine/gateways.yml b/internal/paths/virtual-machine/gateways.yml
deleted file mode 100644
index d56c2f03..00000000
--- a/internal/paths/virtual-machine/gateways.yml
+++ /dev/null
@@ -1,65 +0,0 @@
-get:
-  operationId: "getVirtualMachineGateways"
-  summary: Get Virtual Machine Gateways
-  description: |
-    Returns a list of gateways applicable to the specified virtual machine.
-  tags:
-    - Virtual Machines
-  parameters:
-    - name: virtual-machine-id
-      in: query
-      required: true
-      description: The ID of the virtual machine.
-      schema:
-        type: string
-  responses:
-    default:
-      $ref: ../../../components/responses/errors/DefaultError.yml
-    200:
-      description: Returns a list of gateways applicable to the specified virtual machine.
-      content:
-        application/json:
-          schema:
-            type: object
-            required:
-              - data
-            properties:
-              data:
-                type: array
-                items:
-                  type: object
-                  required:
-                    - virtual_machine_id
-                    - gateway_instance_id
-                  properties:
-                    virtual_machine_id:
-                      $ref: ../../../components/schemas/ID.yml
-                    gateway_instance_id:
-                      $ref: ../../../components/schemas/ID.yml
-                    ips:
-                      type: array
-                      items:
-                        type: object
-                        required:
-                          - kind
-                          - public_ip
-                        properties:
-                          kind:
-                            type: string
-                            description: The type of IP protocol this IP is.
-                            enum:
-                              - ipv4
-                              - ipv6
-                          public_ip:
-                            type: string
-                            description: The public IP attached to the gateway.
-                          gateway_private_ip:
-                            type: 
-                              - string
-                              - "null"
-                            description: The private IP of the gateway.
-                          gateway_nat_ip:
-                            type: 
-                              - string
-                              - "null"
-                            description: The NAT IP of the gateway.
diff --git a/internal/paths/virtual-machine/virtual-machine.yml b/internal/paths/virtual-machine/virtual-machine.yml
index 5524b3ea..97a45d33 100644
--- a/internal/paths/virtual-machine/virtual-machine.yml
+++ b/internal/paths/virtual-machine/virtual-machine.yml
@@ -2,9 +2,13 @@ get:
   operationId: "getVirtualMachine"
   summary: Get Virtual Machine
   description: |
-     Returns a specified virtual machine.
+    Returns a specified virtual machine.
+
+    Requires the `environment` scope to be set on the container runtime config.
   tags:
     - Virtual Machines
+  x-cycle-scopes:
+    - environment
   parameters:
     - name: virtual-machine-id
       in: query
@@ -25,4 +29,4 @@ get:
               - data
             properties:
               data:
-                  $ref: ../../../components/schemas/vms/VirtualMachine.yml
+                $ref: ../../../components/schemas/vms/VirtualMachine.yml
diff --git a/internal/paths/vpn/login.yml b/internal/paths/vpn/login.yml
deleted file mode 100644
index 39ba2c6a..00000000
--- a/internal/paths/vpn/login.yml
+++ /dev/null
@@ -1,42 +0,0 @@
-post:
-  operationId: "validateVPNLogin"
-  summary: Validate VPN Login
-  description: |
-    Validates a username/password pair for logging into the VPN service of the environment of this instance.
-    You must pass a basic Authorization header with the desired username/password combination to validate.
-  tags:
-    - Environments
-    - VPN
-  security:
-    - tokenAuth: []
-    - basicAuth: []
-  parameters: []
-  responses:
-    default:
-      $ref: ../../../components/responses/errors/DefaultError.yml
-    200:
-      description: Returns true on success
-      content:
-        application/json:
-          schema:
-            type: object
-            required:
-              - data
-            properties:
-              data:
-                type: boolean
-                enum:
-                  - true
-    403:
-      description: Returns false on verification failure
-      content:
-        application/json:
-          schema:
-            type: object
-            required:
-              - data
-            properties:
-              data:
-                type: boolean
-                enum:
-                  - false
diff --git a/stackspec/schema/StackSpecContainerConfigRuntime.yml b/stackspec/schema/StackSpecContainerConfigRuntime.yml
index a686d11f..81eb8b0d 100644
--- a/stackspec/schema/StackSpecContainerConfigRuntime.yml
+++ b/stackspec/schema/StackSpecContainerConfigRuntime.yml
@@ -252,6 +252,11 @@ properties:
             - CAP_LEASE
             - CAP_WAKE_ALARM
       - $ref: StackVariable.yml
+  internal_api:
+    oneOf:
+      - $ref: ./runtime/StackSpecRuntimeInternalApi.yml
+      - type: "null"
+      - $ref: StackVariable.yml
   rootfs:
     description: Configuration options for the root filesystem.
     oneOf:
diff --git a/stackspec/schema/runtime/StackSpecRuntimeInternalApi.yml b/stackspec/schema/runtime/StackSpecRuntimeInternalApi.yml
new file mode 100644
index 00000000..8aa5b4bc
--- /dev/null
+++ b/stackspec/schema/runtime/StackSpecRuntimeInternalApi.yml
@@ -0,0 +1,18 @@
+title: StackSpecRuntimeInternalApi
+description: Configuration options for the internal API access within instances of this container.
+type: object
+properties:
+  scope:
+    oneOf:
+      - type: array
+        description: Scopes determine which set of endpoints instances of this container can reach over the internal API.
+        items:
+          type: string
+          enum:
+            - "self"
+            - "environment"
+            - "networks"
+            - "server"
+            - "notifications"
+      - type: "null"
+      - $ref: ../StackVariable.yml

From 3a6f25ae1973813edebc5435868ae3bbe8f9e446 Mon Sep 17 00:00:00 2001
From: Alexander Mattoni <5110855+mattoni@users.noreply.github.com>
Date: Thu, 2 Jul 2026 18:13:46 +0000
Subject: [PATCH 2/2] update tooling and answer comments

---
 .redocly.yaml                                 | 98 -------------------
 .../config/runtime/RuntimeInternalApi.yml     | 10 +-
 internal/paths/ha/checkin.yml                 |  1 +
 internal/paths/hub/hub.yml                    |  1 +
 internal/paths/hub/integration.yml            |  1 +
 internal/paths/monitoring/events.yml          |  1 +
 internal/paths/monitoring/metrics.yml         |  1 +
 internal/paths/server/poweroff.yml            |  1 +
 internal/paths/server/reboot.yml              |  1 +
 package.json                                  |  2 +-
 redocly.yaml                                  | 34 +++++++
 .../runtime/StackSpecRuntimeInternalApi.yml   | 10 +-
 12 files changed, 52 insertions(+), 109 deletions(-)
 delete mode 100644 .redocly.yaml
 create mode 100644 redocly.yaml

diff --git a/.redocly.yaml b/.redocly.yaml
deleted file mode 100644
index 29ed5d38..00000000
--- a/.redocly.yaml
+++ /dev/null
@@ -1,98 +0,0 @@
-# See https://redocly.com/docs/cli/configuration/
-apis:
-  cycle-platform-api:
-    root: ./platform/api.yml
-  cycle-internal-api:
-    root: ./internal/api.yml
-    rules:
-      rule/require-scopes:
-        subject:
-          type: Operation
-          property: x-cycle-scopes
-        assertions:
-          defined: true
-          nonEmpty: true
-        message: Internal API operations must declare x-cycle-scopes.
-        severity: error
-  cycle-scheduler-api:
-    root: ./scheduler/api.yml
-  cycle-ial:
-    root: ./ial/api.yml
-
-extends:
-  - recommended
-
-rules:
-  operation-4xx-response: off
-  no-ambiguous-paths: off
-  # A sample custom rule. Read more about rules: https://redocly.com/docs/cli/rules/
-  # assert/operation-description:
-  #   subject:
-  #     type: Operation
-  #     property: description
-  #   assertions:
-  #     defined: true
-  #     minLength: 30
-  #     pattern: ^[A-Z].+(\.|\.)$
-# features.openapi:
-#   generateCodeSamples:
-#     languages:
-#       - lang: curl
-#       - lang: Node.js
-#       - lang: Python
-theme:
-  openapi:
-    htmlTemplate: ./template/index.html
-    theme:
-      colors:
-        primary:
-          main: "rgb(42, 167, 255)"
-          contrastText: ivory
-        accent:
-          main: rgb(42, 167, 255)
-          contrastText: rgb(42, 167, 255)
-        http:
-          get: rgb(34, 211, 104)
-          post: rgb(42, 167, 255)
-          patch: rgb(174, 55, 255)
-      typography:
-        fontFamily: "'Source Sans 3', sans-serif"
-        links:
-          color: rgb(42, 167, 255)
-        code:
-          color: rgb(42, 167, 255)
-        headings:
-          fontFamily: "'Source Sans 3', sans-serif"
-      schema:
-        requireLabelColor: rgb(255, 198, 41)
-      codeBlock:
-        tokens:
-          property:
-            color: rgb(32, 121, 184) !important
-          string:
-            color: rgb(34, 211, 104)
-          boolean:
-            color: rgb(174, 55, 255)
-      sidebar:
-        backgroundColor: "rgb(30, 30, 33)"
-        textColor: "ivory"
-        activeBgColor: white
-        activeTextColor: rgb(42, 167, 255)
-        borderRadius: 8px
-        rightLineColor: white
-        fontSize: 15px
-        caretColor: rgb(42, 167, 255)
-        spacing:
-          unit: 8px
-          paddingVertical: 16px
-          paddingHorizontal: 8px
-        groupItems:
-          textTransform: uppercase
-          fontWeight: bold
-      rightPanel:
-        textColor: "ivory"
-        backgroundColor: "rgb(18, 18, 21)"
-        panelBackgroundColor: rgb(30, 30, 33)
-        panelControlsBackgroundColor: rgb(18, 18, 21)
-      logo:
-        gutter: 36px
diff --git a/components/schemas/containers/config/runtime/RuntimeInternalApi.yml b/components/schemas/containers/config/runtime/RuntimeInternalApi.yml
index 321ee599..c23564db 100644
--- a/components/schemas/containers/config/runtime/RuntimeInternalApi.yml
+++ b/components/schemas/containers/config/runtime/RuntimeInternalApi.yml
@@ -9,9 +9,9 @@ properties:
         items:
           type: string
           enum:
-            - "self"
-            - "environment"
-            - "networks"
-            - "server"
-            - "notifications"
+            - self
+            - environment
+            - networks
+            - server
+            - notifications
       - type: "null"
diff --git a/internal/paths/ha/checkin.yml b/internal/paths/ha/checkin.yml
index f4c3ec93..ee129a07 100644
--- a/internal/paths/ha/checkin.yml
+++ b/internal/paths/ha/checkin.yml
@@ -9,6 +9,7 @@ post:
   tags:
     - High Availability
   x-cycle-scopes:
+    - none
   requestBody:
     required: true
     content:
diff --git a/internal/paths/hub/hub.yml b/internal/paths/hub/hub.yml
index 7ac942b2..867f989b 100644
--- a/internal/paths/hub/hub.yml
+++ b/internal/paths/hub/hub.yml
@@ -9,6 +9,7 @@ get:
     - Hubs
   parameters: []
   x-cycle-scopes:
+    - none
   responses:
     default:
       $ref: ../../../components/responses/errors/DefaultError.yml
diff --git a/internal/paths/hub/integration.yml b/internal/paths/hub/integration.yml
index f73fd478..97f3b139 100644
--- a/internal/paths/hub/integration.yml
+++ b/internal/paths/hub/integration.yml
@@ -8,6 +8,7 @@ get:
   tags:
     - Hubs
   x-cycle-scopes:
+    - none
   parameters:
     - name: identifier
       in: query
diff --git a/internal/paths/monitoring/events.yml b/internal/paths/monitoring/events.yml
index 45eb5631..229be760 100644
--- a/internal/paths/monitoring/events.yml
+++ b/internal/paths/monitoring/events.yml
@@ -8,6 +8,7 @@ post:
   tags:
     - Monitoring
   x-cycle-scopes:
+    - none
   parameters: []
   requestBody:
     required: true
diff --git a/internal/paths/monitoring/metrics.yml b/internal/paths/monitoring/metrics.yml
index 3768f5fe..5bfda981 100644
--- a/internal/paths/monitoring/metrics.yml
+++ b/internal/paths/monitoring/metrics.yml
@@ -8,6 +8,7 @@ post:
   tags:
     - Monitoring
   x-cycle-scopes:
+    - none
   parameters: []
   requestBody:
     required: true
diff --git a/internal/paths/server/poweroff.yml b/internal/paths/server/poweroff.yml
index 1ae58392..f29270aa 100644
--- a/internal/paths/server/poweroff.yml
+++ b/internal/paths/server/poweroff.yml
@@ -9,6 +9,7 @@ post:
     - Servers
   parameters: []
   x-cycle-scopes:
+    - none
   responses:
     default:
       $ref: ../../../components/responses/errors/DefaultError.yml
diff --git a/internal/paths/server/reboot.yml b/internal/paths/server/reboot.yml
index da7f5d49..9347931a 100644
--- a/internal/paths/server/reboot.yml
+++ b/internal/paths/server/reboot.yml
@@ -9,6 +9,7 @@ post:
     - Servers
   parameters: []
   x-cycle-scopes:
+    - none
   responses:
     default:
       $ref: ../../../components/responses/errors/DefaultError.yml
diff --git a/package.json b/package.json
index 4ba52803..004d04bd 100644
--- a/package.json
+++ b/package.json
@@ -6,7 +6,7 @@
   "scripts": {
     "lint": "npm run lint:platform && npm run lint:internal && npm run lint:scheduler && npm run lint:ial",
     "lint:platform": "npx @redocly/cli lint ./platform/api.yml",
-    "lint:internal": "npx @redocly/cli lint ./internal/api.yml",
+    "lint:internal": "npx @redocly/cli lint cycle-internal-api",
     "lint:scheduler": "npx @redocly/cli lint ./scheduler/api.yml",
     "lint:ial": "npx @redocly/cli lint ./ial/api.yml",
     "build": "npm run build:platform && npm run build:internal && npm run build:scheduler && npm run build:internal",
diff --git a/redocly.yaml b/redocly.yaml
new file mode 100644
index 00000000..76bccfc0
--- /dev/null
+++ b/redocly.yaml
@@ -0,0 +1,34 @@
+# See https://redocly.com/docs/cli/configuration/
+apis:
+  cycle-platform-api:
+    root: ./platform/api.yml
+  cycle-internal-api:
+    root: ./internal/api.yml
+    rules:
+      rule/require-scopes:
+        subject:
+          type: Operation
+          property: x-cycle-scopes
+        assertions:
+          defined: true
+          nonEmpty: true
+          enum:
+            - none
+            - self
+            - environment
+            - networks
+            - server
+            - notifications
+        message: "Internal API operations must declare x-cycle-scopes using one or more of: none, self, environment, networks, server, notifications."
+        severity: error
+  cycle-scheduler-api:
+    root: ./scheduler/api.yml
+  cycle-ial:
+    root: ./ial/api.yml
+
+extends:
+  - recommended
+
+rules:
+  operation-4xx-response: off
+  no-ambiguous-paths: off
diff --git a/stackspec/schema/runtime/StackSpecRuntimeInternalApi.yml b/stackspec/schema/runtime/StackSpecRuntimeInternalApi.yml
index 8aa5b4bc..1278d039 100644
--- a/stackspec/schema/runtime/StackSpecRuntimeInternalApi.yml
+++ b/stackspec/schema/runtime/StackSpecRuntimeInternalApi.yml
@@ -9,10 +9,10 @@ properties:
         items:
           type: string
           enum:
-            - "self"
-            - "environment"
-            - "networks"
-            - "server"
-            - "notifications"
+            - self
+            - environment
+            - networks
+            - server
+            - notifications
       - type: "null"
       - $ref: ../StackVariable.yml