Update route policies and domains

docs/openapi/apis/cf/latest/components/requestBodies/DomainCreateRequestBody.yaml

@@ -9,31 +9,53 @@ content:
       properties:
         name:
           type: string
-          description: Name of the domain
+          description: Name of the domain; must be unique (case-insensitive)
         internal:
           type: boolean
-          description: Whether the domain is used for internal (container-to-container) traffic
+          default: false
+          description: Whether the domain is used for internal (container-to-container) traffic, or external (user-to-container) traffic
         router_group:
           type: object
           properties:
             guid:
               type: string
               format: uuid
-          description: 'The desired router group guid.  _note: creates a `tcp` domain; cannot be used when `internal` is set to `true` or domain is scoped to an org_'
+              description: The desired router group guid
+          description: 'The desired router group. _note: creates a `tcp` domain; cannot be used when `internal` is set to `true` or domain is scoped to an org_'
+        enforce_route_policies:
+          type: boolean
+          default: false
+          description: When `true`, GoRouter enforces route policies for routes on this domain using mutual TLS (mTLS). Set at creation only; cannot be changed on update. Cannot be used with internal domains
+        route_policies_scope:
+          type: string
+          enum:
+            - any
+            - org
+            - space
+          description: 'Operator-defined boundary for allowed callers: `any`, `org`, or `space`. Required when `enforce_route_policies` is `true`. Set at creation only; cannot be changed on update'
         relationships:
           type: object
           properties:
             organization:
               $ref: ../schemas/RelationshipToOne.yaml
-              description: A relationship to the organization the domain will be scoped to;  _note cannot be used when `internal` is set to `true` or domain is associated with a router group_
+              description: 'A relationship to the organization the domain will be scoped to; _note: cannot be used when `internal` is set to `true` or domain is associated with a router group_'
             shared_organizations:
               $ref: ../schemas/RelationshipToMany.yaml
-              description: A relationship to organizations the domain will be shared with  _Note cannot be used without an organization relationship_
+              description: 'A relationship to organizations the domain will be shared with. _Note: cannot be used without an organization relationship_'
+          description: Relationships to the organization the domain will be scoped to and the organizations the domain will be shared with
         metadata:
           $ref: ../schemas/Metadata.yaml
+          description: Labels and annotations applied to the domain
     examples:
       default:
         summary: default
         value:
           name: example.com
           internal: false
+      identityAwareDomain:
+        summary: Identity-aware domain
+        value:
+          name: apps.identity
+          internal: false
+          enforce_route_policies: true
+          route_policies_scope: org

docs/openapi/apis/cf/latest/components/requestBodies/DomainUpdateRequestBody.yaml

@@ -7,4 +7,14 @@ content:
       properties:
         metadata:
           $ref: '../schemas/Metadata.yaml'
+          description: Labels and annotations applied to the domain
       description: Request schema for updating a domain
+    examples:
+      default:
+        summary: default
+        value:
+          metadata:
+            labels:
+              key: value
+            annotations:
+              note: detailed information

docs/openapi/apis/cf/latest/components/requestBodies/IsolationSegmentCreate.yaml

@@ -1,14 +1,16 @@
 description: Isolation segment to create
+required: true
 content:
   application/json:
     schema:
       type: object
       properties:
         name:
           type: string
-          description: Name of the isolation segment; isolation segment names must be unique across the entire system, and case is ignored when checking for uniqueness
+          description: Name of the isolation segment; must be unique (case-insensitive)
         metadata:
           $ref: ../schemas/Metadata.yaml
+          description: Labels and annotations applied to the isolation segment
       required:
         - name
     examples:

docs/openapi/apis/cf/latest/components/requestBodies/RoutePolicyCreateRequestBody.yaml

@@ -0,0 +1,55 @@
+description: Route policy to create
+required: true
+content:
+  application/json:
+    schema:
+      type: object
+      properties:
+        source:
+          type: string
+          description: The policy selector. Must be `cf:app:<uuid>`, `cf:space:<uuid>`, `cf:org:<uuid>`, or `cf:any`
+        relationships:
+          type: object
+          properties:
+            route:
+              $ref: ../schemas/RelationshipToOne.yaml
+              description: The route this policy applies to
+          required:
+            - route
+          description: A relationship to the route this policy applies to
+        metadata:
+          $ref: ../schemas/Metadata.yaml
+          description: Labels and annotations applied to the route policy
+      required:
+        - source
+        - relationships
+    examples:
+      default:
+        summary: Allow specific app
+        value:
+          source: cf:app:d76446a1-f429-4444-8797-be2f78b75b08
+          relationships:
+            route:
+              data:
+                guid: 89b32bd6-688f-4424-b94f-2e2c86495a5f
+          metadata:
+            labels:
+              team: frontend
+            annotations:
+              description: Allow frontend app to call backend API
+      space:
+        summary: Allow all apps in a space
+        value:
+          source: cf:space:3fa85f64-5717-4562-b3fc-2c963f66afa6
+          relationships:
+            route:
+              data:
+                guid: 89b32bd6-688f-4424-b94f-2e2c86495a5f
+      any:
+        summary: Allow any caller
+        value:
+          source: cf:any
+          relationships:
+            route:
+              data:
+                guid: 89b32bd6-688f-4424-b94f-2e2c86495a5f

docs/openapi/apis/cf/latest/components/requestBodies/RoutePolicyUpdateRequestBody.yaml

@@ -0,0 +1,19 @@
+description: Route policy metadata to update
+required: true
+content:
+  application/json:
+    schema:
+      type: object
+      properties:
+        metadata:
+          $ref: ../schemas/Metadata.yaml
+          description: Labels and annotations applied to the route policy
+    examples:
+      default:
+        summary: default
+        value:
+          metadata:
+            labels:
+              team: backend
+            annotations:
+              note: Updated contact info

docs/openapi/apis/cf/latest/components/schemas/Domain.yaml

@@ -9,14 +9,15 @@ allOf:
         type: boolean
         description: Whether the domain is used for internal (container-to-container) traffic
       router_group:
-        type: 
+        type:
           - object
           - 'null'
         properties:
           guid:
             type: string
             format: uuid
-        description: The guid of the desired router group to route `tcp` traffic through; if set, the domain will only be available for `tcp` traffic
+            description: The guid of the desired router group to route `tcp` traffic through; if set, the domain will only be available for `tcp` traffic
+        description: The router group the domain routes `tcp` traffic through; if set, the domain will only be available for `tcp` traffic
       supported_protocols:
         type: array
         items:
@@ -25,10 +26,29 @@ allOf:
             - http
             - tcp
         description: Available protocols for routes using the domain, currently `http` and `tcp`
+      enforce_route_policies:
+        type: boolean
+        description: When `true`, GoRouter enforces route policies for routes on this domain. This field only appears in the response when set to `true`. Set at creation only; cannot be changed on update
+      route_policies_scope:
+        type: string
+        enum:
+          - any
+          - org
+          - space
+        description: 'Operator-defined boundary for allowed callers: `any`, `org`, or `space`. Required when `enforce_route_policies` is `true`. This field only appears when `enforce_route_policies` is `true`. Set at creation only; cannot be changed on update'
       relationships:
-        $ref: './Relationships.yaml'
+        type: object
+        properties:
+          organization:
+            $ref: './RelationshipToOne.yaml'
+            description: The organization the domain is scoped to; if set, the domain will only be available in that organization; otherwise, the domain will be globally available
+          shared_organizations:
+            $ref: './RelationshipToMany.yaml'
+            description: Organizations the domain is shared with; if set, the domain will be available in these organizations in addition to the organization the domain is scoped to
+        description: Relationships to the organization the domain is scoped to and the organizations the domain is shared with
       metadata:
         $ref: './Metadata.yaml'
+        description: Labels and annotations applied to the domain
       links:
         type: object
         properties:
@@ -37,15 +57,18 @@ allOf:
             description: The URL to get this domain
           organization:
             $ref: './Link.yaml'
-            description: The URL to get the organization for this domain
+            description: The URL to get the organization this domain is scoped to; only present for organization-scoped domains
           route_reservations:
             $ref: './Link.yaml'
-            description: The URL to get the route reservations for this domain
+            description: The URL to check which routes are reserved for this domain
           shared_organizations:
             $ref: './Link.yaml'
-            description: The URL to get the shared organizations for this domain
+            description: The URL to get the organizations this domain is shared with; only present for organization-scoped domains
           router_group:
             $ref: './Link.yaml'
-            description: The URL to get the router group for this domain
-description: |
-  A domain is a fully qualified domain name that is used for application routes. A domain can be scoped to an organization, meaning it can be used to create routes for spaces inside that organization, or be left unscoped to allow all organizations access.
+            description: The URL to get the router group for this domain; only present for domains associated with a router group
+        description: Links to related resources
+description: |-
+  Domains represent a [fully qualified domain name](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) that is used for application routes.
+
+  A domain can be scoped to an organization, meaning it can be used to create routes for spaces inside that organization, or be left unscoped to allow all organizations access.

docs/openapi/apis/cf/latest/components/schemas/DomainList.yaml

@@ -2,7 +2,10 @@ type: object
 properties:
   pagination:
     $ref: './Pagination.yaml'
+    description: Pagination information for the list of domains
   resources:
     type: array
     items:
       $ref: './Domain.yaml'
+    description: List of domains
+description: A paginated list of domains

docs/openapi/apis/cf/latest/components/schemas/IsolationSegment.yaml

@@ -4,9 +4,10 @@ allOf:
   - properties:
       name:
         type: string
-        description: The name of the isolation segment
+        description: Name of the isolation segment
       metadata:
         $ref: './Metadata.yaml'
+        description: Labels and annotations on the isolation segment
       links:
         type: object
         properties:
@@ -15,5 +16,6 @@ allOf:
             description: The URL to get this isolation segment
           organizations:
             $ref: './Link.yaml'
-            description: The URL to get the organizations for this isolation segment
-description: An isolation segment provides a dedicated pool of compute resources for an organization or space.
+            description: The URL to get the organizations entitled to this isolation segment
+        description: Links to related resources
+description: Isolation Segments provide dedicated pools of resources to which apps can be deployed to isolate workloads.

docs/openapi/apis/cf/latest/components/schemas/IsolationSegmentList.yaml

@@ -2,7 +2,10 @@ type: object
 properties:
   pagination:
     $ref: './Pagination.yaml'
+    description: Pagination information for the list of isolation segments
   resources:
     type: array
     items:
       $ref: './IsolationSegment.yaml'
+    description: List of isolation segments
+description: A paginated list of isolation segments

docs/openapi/apis/cf/latest/components/schemas/RoutePolicy.yaml

@@ -0,0 +1,65 @@
+type: object
+allOf:
+  - $ref: './BaseSchema.yaml'
+  - properties:
+      source:
+        type: string
+        description: |-
+          The policy selector specifying who can access the route. Must be one of:
+          - `cf:app:<uuid>` (specific app)
+          - `cf:space:<uuid>` (all apps in a space)
+          - `cf:org:<uuid>` (all apps in an organization)
+          - `cf:any` (any caller - cannot be combined with other sources)
+      metadata:
+        $ref: './Metadata.yaml'
+        description: Labels and annotations applied to the route policy
+      relationships:
+        type: object
+        properties:
+          route:
+            $ref: './RelationshipToOne.yaml'
+            description: The route this policy applies to
+          app:
+            $ref: './RelationshipToOne.yaml'
+            description: Read-only. Always present; `data` is `null` unless the source is `cf:app:<uuid>`
+          space:
+            $ref: './RelationshipToOne.yaml'
+            description: Read-only. Always present; `data` is `null` unless the source is `cf:space:<uuid>`
+          organization:
+            $ref: './RelationshipToOne.yaml'
+            description: Read-only. Always present; `data` is `null` unless the source is `cf:org:<uuid>`
+        description: Relationships to the route this policy applies to and to the app, space, or organization referenced by the source
+      links:
+        type: object
+        properties:
+          self:
+            $ref: './Link.yaml'
+            description: The URL to get this route policy
+          route:
+            $ref: './Link.yaml'
+            description: The URL to get the route this policy applies to
+          app:
+            $ref: './Link.yaml'
+            description: The URL to get the app referenced by the source; only present when the source is `cf:app:<uuid>`
+          space:
+            $ref: './Link.yaml'
+            description: The URL to get the space referenced by the source; only present when the source is `cf:space:<uuid>`
+          organization:
+            $ref: './Link.yaml'
+            description: The URL to get the organization referenced by the source; only present when the source is `cf:org:<uuid>`
+        description: Links to related resources. Always includes `self` and `route`; includes `app`, `space`, or `organization` when the source references that resource
+      included:
+        $ref: './IncludedResources.yaml'
+        description: Additional related resources included in the response when using the include parameter
+description: |-
+  Route policies control which Cloud Foundry apps, spaces, or organizations can access routes on identity-aware domains. When a domain has `enforce_route_policies` enabled, GoRouter automatically enforces these access controls using mutual TLS (mTLS) to verify the identity of the calling application.
+
+  Route policies are defined using a `source` selector that specifies who can access the route:
+  - `cf:app:<uuid>` - Allow a specific app
+  - `cf:space:<uuid>` - Allow all apps in a space
+  - `cf:org:<uuid>` - Allow all apps in an organization
+  - `cf:any` - Allow any caller (cannot be combined with other sources on the same route)
+
+  > **Note:** Route policies can only be created for routes on domains where `enforce_route_policies` is `true` and the domain is not internal (internal routes use container-to-container networking and bypass GoRouter).
+
+  **This feature is experimental and is subject to change.**

docs/openapi/apis/cf/latest/components/schemas/RoutePolicyList.yaml

@@ -0,0 +1,13 @@
+type: object
+properties:
+  pagination:
+    $ref: './Pagination.yaml'
+  resources:
+    type: array
+    items:
+      $ref: './RoutePolicy.yaml'
+    description: List of route policies
+  included:
+    $ref: './IncludedResources.yaml'
+    description: Additional related resources included in the response when using the include parameter
+description: A list of route policies

docs/openapi/apis/cf/latest/openapi.yaml

@@ -60,6 +60,8 @@ tags:
     description: "Root API endpoints that provide entry points and API information."
   - name: Routes
     description: "Routes are used to map a URL to an app."
+  - name: Route Policies
+    description: "Route policies control which callers can access routes on identity-aware domains."
   - name: Security Groups
     description: "Security groups are used to control access to apps."
   - name: Service Brokers
@@ -464,6 +466,10 @@ paths:
     $ref: './paths/Roles.yaml#/~1v3~1roles'
   /v3/roles/{guid}:
     $ref: './paths/Roles.yaml#/~1v3~1roles~1{guid}'
+  /v3/route_policies:
+    $ref: './paths/RoutePolicies.yaml#/~1v3~1route_policies'
+  /v3/route_policies/{guid}:
+    $ref: './paths/RoutePolicies.yaml#/~1v3~1route_policies~1{guid}'
   /v3/routes:
     $ref: './paths/Routes.yaml#/~1v3~1routes'
   /v3/routes/{guid}/destinations: