@celigo/api-specs 0.2.64 → 0.2.66

package/dist/networkpolicy.yml

@@ -0,0 +1,1221 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: Network Policies
+  description: Manage IP allow and deny lists that restrict where API tokens, MCP servers, and users may connect from.
+  x-celigo-ai-guidance:
+    - |-
+      API for managing network policies — named IP allow/deny lists that are assigned to API tokens
+      (`_networkPolicyId`), MCP servers (`_networkPolicyId`), or account sign-in settings to restrict
+      the source addresses a caller may connect from. A policy restricts nothing until it is assigned.
+servers:
+  - url: https://api.integrator.io
+    description: Production (US / default region)
+  - url: https://api.eu.integrator.io
+    description: Production (EU region)
+  - url: https://api.au.integrator.io
+    description: Production (AU region)
+  - url: https://api.ca.integrator.io
+    description: Production (CA region)
+security:
+  - bearerAuth: []
+tags:
+  - name: Network Policies
+    description: |-
+      Network policies are named IP allow and deny lists that control where API tokens, MCP servers, and users may connect from. A policy takes effect only once it is assigned — through `_networkPolicyId` on an API token or MCP server, or in account settings for workspace-user and end-user sign-in — and each environment (production or sandbox) keeps its own library of policies. Network policies must be enabled for the account, and only the account owner and administrators can manage them.
+
+      ## Network policy schema
+
+      {% openapi-schemas spec="networkpolicy" schemas="NetworkPolicy" grouped="true" %}
+paths:
+  /v1/networkpolicies:
+    get:
+      x-internal: false
+      summary: List network policies
+      description: |-
+        Returns the policies of the caller's environment, most recently modified first.
+        Policies in the recycle bin are not included. The `include` and `exclude`
+        projection parameters used by other list endpoints are not supported here.
+      operationId: listNetworkPolicies
+      tags:
+        - Network Policies
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          description: Maximum number of policies to return per page.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            examples:
+              - 100
+        - name: sort_by
+          in: query
+          required: false
+          description: |-
+            Field to order the page by. `lastModified` lists the most recently changed
+            policy first; `name` lists alphabetically.
+          schema:
+            type: string
+            enum:
+              - lastModified
+              - name
+            x-enumDescriptions:
+              lastModified: Most recently modified policy first
+              name: Alphabetical by display name
+            examples:
+              - name
+        - $ref: '#/components/parameters/After'
+      responses:
+        '200':
+          description: Array of network policies.
+          headers:
+            Link:
+              description: |-
+                RFC 5988 pagination links. When more pages remain, includes a
+                `<...>; rel="next"` entry with an `after` cursor; absent on the
+                final page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/NetworkPolicy'
+              examples:
+                default:
+                  value:
+                    - _id: 6ab1f501b9e454749402c749
+                      _userId: 624cb0346309dc3a543733a2
+                      name: Corporate VPN egress
+                      description: Office and VPN egress ranges. Deny beats allow.
+                      ipAllowList:
+                        - 10.0.0.0/8
+                        - 203.0.113.5/32
+                        - 2001:db8::/32
+                      ipDenyList:
+                        - 198.51.100.0/24
+                      createdAt: '2026-09-22T03:24:49.115Z'
+                      lastModified: '2026-09-22T03:27:28.318Z'
+                    - _id: 6ab1ebbfb9e4547494ff7558
+                      _userId: 624cb0346309dc3a543733a2
+                      name: Block known scanners
+                      ipAllowList: []
+                      ipDenyList:
+                        - 198.51.100.7/32
+                        - 192.0.2.0/24
+                      createdAt: '2026-09-22T02:45:19.304Z'
+                      lastModified: '2026-09-22T02:45:19.304Z'
+        '204':
+          description: No network policies exist in this environment.
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    post:
+      x-internal: false
+      summary: Create a network policy
+      description: |-
+        Creates a policy in the caller's environment. Entries in both lists are
+        validated and stored in normalized form — a bare address becomes `/32` or
+        `/128`, IPv6 is compressed — and the response shows the stored values. The new
+        policy restricts nothing until it is assigned to an API token, an MCP server,
+        or account sign-in.
+      operationId: createNetworkPolicy
+      tags:
+        - Network Policies
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              allowList:
+                summary: Allow only corporate ranges
+                value:
+                  name: Corporate VPN egress
+                  description: Office and VPN egress ranges. Deny beats allow.
+                  ipAllowList:
+                    - 10.0.0.0/8
+                    - 203.0.113.5
+                    - 2001:db8::/32
+                  ipDenyList:
+                    - 198.51.100.0/24
+              denyOnly:
+                summary: Deny list only
+                value:
+                  name: Block known scanners
+                  ipDenyList:
+                    - 198.51.100.7
+                    - 192.0.2.0/24
+      responses:
+        '201':
+          description: Created network policy, with entries in stored form.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/NetworkPolicy'
+              examples:
+                allowList:
+                  summary: Created policy
+                  value:
+                    _id: 6ab1f501b9e454749402c749
+                    _userId: 624cb0346309dc3a543733a2
+                    name: Corporate VPN egress
+                    description: Office and VPN egress ranges. Deny beats allow.
+                    ipAllowList:
+                      - 10.0.0.0/8
+                      - 203.0.113.5/32
+                      - 2001:db8::/32
+                    ipDenyList:
+                      - 198.51.100.0/24
+                    createdAt: '2026-09-22T03:24:49.115Z'
+                    lastModified: '2026-09-22T03:24:49.115Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '409':
+          $ref: '#/components/responses/409-name-conflict'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/networkpolicies/{_id}:
+    get:
+      x-internal: false
+      summary: Get a network policy
+      description: |-
+        Returns a single policy from the caller's environment. A policy that has been
+        moved to the recycle bin, or that belongs to another environment, returns 404.
+      operationId: getNetworkPolicyById
+      tags:
+        - Network Policies
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Network policy ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: networkpolicies
+            examples:
+              - 6ab1f501b9e454749402c749
+      responses:
+        '200':
+          description: Network policy.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/NetworkPolicy'
+              examples:
+                default:
+                  value:
+                    _id: 6ab1f501b9e454749402c749
+                    _userId: 624cb0346309dc3a543733a2
+                    name: Corporate VPN egress
+                    description: Office and VPN egress ranges. Deny beats allow.
+                    ipAllowList:
+                      - 10.0.0.0/8
+                      - 203.0.113.5/32
+                      - 2001:db8::/32
+                    ipDenyList:
+                      - 198.51.100.0/24
+                    createdAt: '2026-09-22T03:24:49.115Z'
+                    lastModified: '2026-09-22T03:27:28.318Z'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    put:
+      x-internal: false
+      summary: Replace a network policy
+      description: |-
+        Replaces the policy with the request body. Fields left out are cleared: an
+        omitted `description` is removed and an omitted `ipAllowList` or `ipDenyList`
+        becomes empty, which lifts every restriction that list imposed. Entries are
+        validated and normalized exactly as on create. The change applies to every
+        token, MCP server, and sign-in setting the policy is assigned to.
+      operationId: updateNetworkPolicy
+      tags:
+        - Network Policies
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Network policy ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: networkpolicies
+            examples:
+              - 6ab1f501b9e454749402c749
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              addRange:
+                summary: Add a range to the allow list
+                value:
+                  name: Corporate VPN egress
+                  description: Office and VPN egress ranges. Deny beats allow.
+                  ipAllowList:
+                    - 10.0.0.0/8
+                    - 203.0.113.5
+                    - 2001:db8::/32
+                    - 172.16.0.0/12
+                  ipDenyList:
+                    - 198.51.100.0/24
+      responses:
+        '200':
+          description: Updated network policy, with entries in stored form.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/NetworkPolicy'
+              examples:
+                addRange:
+                  summary: Updated policy
+                  value:
+                    _id: 6ab1f501b9e454749402c749
+                    _userId: 624cb0346309dc3a543733a2
+                    name: Corporate VPN egress
+                    description: Office and VPN egress ranges. Deny beats allow.
+                    ipAllowList:
+                      - 10.0.0.0/8
+                      - 203.0.113.5/32
+                      - 2001:db8::/32
+                      - 172.16.0.0/12
+                    ipDenyList:
+                      - 198.51.100.0/24
+                    createdAt: '2026-09-22T03:24:49.115Z'
+                    lastModified: '2026-09-22T03:30:21.527Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '409':
+          $ref: '#/components/responses/409-name-conflict'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    patch:
+      x-internal: false
+      summary: Patch a network policy
+      description: |-
+        Partially updates a policy with a JSON Patch document (RFC 6902). Fields the
+        document does not touch are preserved, unlike PUT. Whitelisted paths:
+
+        | Path | Operations |
+        |------|------------|
+        | `/name` | `add`, `replace` |
+        | `/description` | `add`, `replace`, `remove` |
+        | `/ipAllowList`, `/ipDenyList` | `replace` the whole list |
+        | `/ipAllowList/-`, `/ipDenyList/-` | `add` one entry at the end |
+        | `/ipAllowList/{index}`, `/ipDenyList/{index}` | `add` or `replace` one entry |
+
+        Entries are validated and normalized exactly as on create. `move`, `copy`, and
+        `test` on `/name` or either list return 400 `invalid_patch_operation`; removing
+        a single list entry by index is not supported (422) — `replace` the whole list
+        instead. Any other path returns 422.
+      operationId: patchNetworkPolicy
+      tags:
+        - Network Policies
+      x-celigo-ai-guidance:
+        - |-
+          To drop one address from a list, `replace` the whole list without it — `remove` on
+          `/ipAllowList/0` fails with 422 "Remove at array index is not supported". Read the policy
+          first so the replacement starts from the stored, normalized entries.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Network policy ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: networkpolicies
+            examples:
+              - 6ab1f501b9e454749402c749
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/JsonPatchRequest'
+            examples:
+              rename:
+                summary: Rename the policy
+                value:
+                  - op: replace
+                    path: /name
+                    value: Corporate VPN egress (2026)
+              appendEntry:
+                summary: Append one address to the deny list
+                value:
+                  - op: add
+                    path: /ipDenyList/-
+                    value: 198.51.100.7
+              replaceList:
+                summary: Replace the allow list
+                value:
+                  - op: replace
+                    path: /ipAllowList
+                    value:
+                      - 10.0.0.0/8
+                      - 172.16.0.0/12
+              clearDescription:
+                summary: Remove the description
+                value:
+                  - op: remove
+                    path: /description
+      responses:
+        '204':
+          description: Network policy patched.
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '409':
+          $ref: '#/components/responses/409-name-conflict'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    delete:
+      x-internal: false
+      summary: Delete a network policy
+      description: |-
+        Moves the policy to the recycle bin, where it is retained for 30 days and can
+        be restored. A policy that is still assigned to an API token, MCP server, or
+        account sign-in setting is not deleted: the request fails with 409
+        `network_policy_in_use` and `info` lists every assignment. Repeat with
+        `force=true` to clear those assignments and delete the policy — every principal
+        it was assigned to loses the restriction. Use `GET /v1/networkpolicies/{_id}/dependencies`
+        to review the assignments first.
+      operationId: deleteNetworkPolicy
+      tags:
+        - Network Policies
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Network policy ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: networkpolicies
+            examples:
+              - 6ab1f501b9e454749402c749
+        - name: force
+          in: query
+          required: false
+          description: |-
+            When true, clears the policy from every API token, MCP server, and account
+            sign-in setting it is assigned to, then deletes it. Without it, an assigned
+            policy returns 409 and nothing changes.
+          schema:
+            type: boolean
+            default: false
+            examples:
+              - true
+      responses:
+        '204':
+          description: Network policy moved to the recycle bin.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '409':
+          $ref: '#/components/responses/409-in-use'
+  /v1/networkpolicies/{_id}/dependencies:
+    get:
+      x-internal: false
+      operationId: listNetworkPolicyDependencies
+      tags:
+        - Network Policies
+      summary: List assignments of a network policy
+      description: |-
+        Returns every API token, MCP server, and account sign-in setting the policy is
+        assigned to within its own environment. Call it before `DELETE` to see what a
+        `force=true` delete would clear. Unlike other `/dependencies` endpoints, the
+        response is a fixed object rather than a map keyed by resource type.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Network policy ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: networkpolicies
+            examples:
+              - 6ab1f501b9e454749402c749
+      responses:
+        '200':
+          description: Assignments of the policy. All keys are present even when the policy is unassigned.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/NetworkPolicyDependencies'
+              examples:
+                assigned:
+                  summary: Assigned to an MCP server
+                  value:
+                    mcpservers:
+                      - _id: 6ab1f4a95af4c5a3ea6b0a28
+                        name: Order lookup MCP server
+                    accesstokens: []
+                    account:
+                      workspaceUsers: false
+                      workspaceUserEnvironments: []
+                      endUsers: false
+                      endUserEnvironments: []
+                unassigned:
+                  summary: Not assigned anywhere
+                  value:
+                    mcpservers: []
+                    accesstokens: []
+                    account:
+                      workspaceUsers: false
+                      workspaceUserEnvironments: []
+                      endUsers: false
+                      endUserEnvironments: []
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/networkpolicies/{_id}/audit:
+    get:
+      x-internal: false
+      summary: Get audit log for a network policy
+      description: |-
+        Returns the change history for a network policy, newest first. Each entry
+        records one event with who made the change, when, and which fields were
+        affected. Entries survive the policy's deletion and purge; the route itself
+        returns 404 once the policy has been purged, so use `GET /v1/audit?resourceType=networkpolicy`
+        to read the history of a purged policy.
+      tags:
+        - Network Policies
+      operationId: getNetworkPolicyAudit
+      parameters:
+        - name: _id
+          in: path
+          description: Network policy ID.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: networkpolicies
+            examples:
+              - 6ab1f501b9e454749402c749
+        - name: limit
+          in: query
+          description: Maximum number of audit entries to return per page.
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            default: 1000
+            examples:
+              - 100
+        - name: after
+          in: query
+          required: false
+          description: |-
+            Opaque pagination cursor for the next page. Take it from the `after` value in the `Link`
+            response header's `rel="next"` URL rather than constructing it.
+          schema:
+            type: string
+            examples:
+              - W3siJGRhdGUiOiIyMDI2LTA5LTIyVDAzOjI3OjEwLjM5N1oifSwiNmFiMWY1OGU0ZGI1Njg4ZmQ4Y2FjMTc5Il0
+        - name: from
+          in: query
+          required: false
+          description: Only return entries at or after this timestamp.
+          schema:
+            type: string
+            format: date-time
+            examples:
+              - '2026-09-01T00:00:00.000Z'
+        - name: to
+          in: query
+          required: false
+          description: Only return entries at or before this timestamp.
+          schema:
+            type: string
+            format: date-time
+            examples:
+              - '2026-09-30T23:59:59.999Z'
+        - name: action
+          in: query
+          required: false
+          description: Filter by the change type. Maps to the `event` field on each entry.
+          schema:
+            type: string
+            enum:
+              - create
+              - update
+              - delete
+              - view
+              - restore
+              - purge
+              - signin
+              - signout
+              - purgelogs
+            examples:
+              - update
+            x-enumDescriptions:
+              create: A resource was created.
+              update: A resource was modified.
+              delete: A resource was deleted (moved to recycle bin).
+              view: A resource was viewed or accessed.
+              restore: A resource was restored from the recycle bin.
+              purge: A resource was permanently purged from the recycle bin.
+              signin: A user signed in to the account.
+              signout: A user signed out of the account.
+              purgelogs: Execution logs were purged for a resource.
+        - name: source
+          in: query
+          required: false
+          description: Filter by how the change was initiated.
+          schema:
+            type: string
+            enum:
+              - ui
+              - api
+              - system
+              - connector
+              - script
+              - sso
+            examples:
+              - api
+            x-enumDescriptions:
+              ui: Change made through the Celigo web UI.
+              api: Change made via the REST API.
+              system: Change made automatically by the platform.
+              connector: Change made by an Integration App (connector) process.
+              script: Change made by a custom script execution.
+              sso: Change triggered by an SSO authentication event.
+        - name: _byUserId
+          in: query
+          required: false
+          description: Filter to changes performed by a single user.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: users
+            examples:
+              - 624cb0346309dc3a543733a2
+      responses:
+        '200':
+          description: Array of audit entries, newest first.
+          headers:
+            Link:
+              description: |-
+                RFC 5988 pagination link. Includes `<...>; rel="next"` with an
+                `after` cursor when more entries exist; absent on the final page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    _id:
+                      type: string
+                      format: objectId
+                      description: Unique identifier for this audit entry.
+                      examples:
+                        - 6ab1f5a0b9e454749402f002
+                    resourceType:
+                      type: string
+                      description: Always `networkpolicy` for this endpoint.
+                      examples:
+                        - networkpolicy
+                    _resourceId:
+                      type: string
+                      format: objectId
+                      x-celigo-refModel: networkpolicies
+                      description: ID of the network policy this entry belongs to.
+                      examples:
+                        - 6ab1f501b9e454749402c749
+                    event:
+                      type: string
+                      description: |-
+                        Type of change that occurred. A policy's history runs `create`, then any
+                        number of `update`, then `delete`; a deleted policy either gains a
+                        `restore` and continues, or ends with `purge`.
+                      enum:
+                        - create
+                        - update
+                        - delete
+                        - restore
+                        - purge
+                      x-enumDescriptions:
+                        create: Policy was created
+                        update: Policy fields were modified
+                        delete: Policy was moved to the recycle bin
+                        restore: Policy was restored from the recycle bin
+                        purge: Policy was permanently removed from the recycle bin
+                    source:
+                      type: string
+                      description: How the change was initiated. Restores from the recycle bin are recorded as `system`.
+                      enum:
+                        - api
+                        - ui
+                        - system
+                      x-enumDescriptions:
+                        api: Change made via the REST API
+                        ui: Change made through the Celigo UI
+                        system: Change made by an automated platform process
+                    time:
+                      type: string
+                      format: date-time
+                      description: When the change occurred.
+                      examples:
+                        - '2026-09-22T03:27:28.318Z'
+                    byUser:
+                      type: object
+                      description: User who made the change.
+                      properties:
+                        _id:
+                          type: string
+                          format: objectId
+                          x-celigo-refModel: users
+                          description: User ID.
+                          examples:
+                            - 624cb0346309dc3a543733a2
+                        email:
+                          type: string
+                          format: email
+                          description: User email address.
+                          examples:
+                            - user@example.com
+                        name:
+                          type: string
+                          description: User display name.
+                          examples:
+                            - Jane Doe
+                    fieldChanges:
+                      type: array
+                      description: Fields that were modified. Empty on `create`, `delete`, `restore`, and `purge` events.
+                      items:
+                        type: object
+                        properties:
+                          fieldPath:
+                            type: string
+                            description: Dot-notation path of the changed field.
+                            examples:
+                              - ipAllowList
+                          oldValue:
+                            description: Previous value (absent when the field was newly set).
+                          newValue:
+                            description: New value (absent when the field was removed).
+                    deletedInfo:
+                      type: object
+                      description: Metadata about the deleted policy. Present on `delete` and `purge` events.
+                      properties:
+                        name:
+                          type: string
+                          description: Name of the policy at the time of deletion.
+                          examples:
+                            - Corporate VPN egress
+              examples:
+                default:
+                  value:
+                    - _id: 6ab1f5a0b9e454749402f002
+                      resourceType: networkpolicy
+                      _resourceId: 6ab1f501b9e454749402c749
+                      source: api
+                      event: update
+                      time: '2026-09-22T03:27:28.318Z'
+                      byUser:
+                        _id: 624cb0346309dc3a543733a2
+                        email: user@example.com
+                        name: Jane Doe
+                      fieldChanges:
+                        - fieldPath: ipAllowList
+                          oldValue:
+                            - 10.0.0.0/8
+                          newValue:
+                            - 10.0.0.0/8
+                            - 172.16.0.0/12
+                    - _id: 6ab1f501b9e454749402c752
+                      resourceType: networkpolicy
+                      _resourceId: 6ab1f501b9e454749402c749
+                      source: api
+                      event: create
+                      time: '2026-09-22T03:24:49.115Z'
+                      byUser:
+                        _id: 624cb0346309dc3a543733a2
+                        email: user@example.com
+                        name: Jane Doe
+                      fieldChanges: []
+        '204':
+          description: No audit entries exist for this network policy.
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  parameters:
+    After:
+      name: after
+      in: query
+      required: false
+      description: |-
+        Opaque cursor for forward pagination. Pass the value from the `Link`
+        response header (`rel="next"`) to fetch the next page.
+      schema:
+        type: string
+  schemas:
+    NetworkPolicy:
+      type: object
+      description: Network policy as returned by the API.
+      x-celigo-ai-guidance:
+        - |-
+          Responses return the stored, normalized lists: a bare address comes back with `/32` (IPv4) or
+          `/128` (IPv6) appended and IPv6 ranges are compressed and lowercased, so compare against the
+          returned form rather than the value that was sent.
+      required:
+        - _id
+        - _userId
+        - name
+        - ipAllowList
+        - ipDenyList
+        - createdAt
+        - lastModified
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: networkpolicies
+          description: Unique identifier for the network policy.
+          examples:
+            - 6ab1f501b9e454749402c749
+        _userId:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: users
+          description: |-
+            Environment that owns the policy — the account user for production, or the
+            sandbox user for a policy created there. A policy is visible and assignable
+            only within its own environment.
+          examples:
+            - 624cb0346309dc3a543733a2
+        name:
+          type: string
+          maxLength: 150
+          description: Display name shown wherever a policy is picked or listed. Unique among the environment's policies that are not in the recycle bin.
+          examples:
+            - Corporate VPN egress
+        description:
+          type: string
+          maxLength: 500
+          description: Explains what the policy is for. Absent when the policy has no description.
+          examples:
+            - Office and VPN egress ranges. Deny beats allow.
+        ipAllowList:
+          type: array
+          maxItems: 200
+          description: |-
+            Source addresses permitted to connect, each an IPv4 or IPv6 address or CIDR
+            range in stored form (bare addresses carry `/32` or `/128`). An empty list
+            permits every address that `ipDenyList` does not block.
+          items:
+            type: string
+          examples:
+            - - 10.0.0.0/8
+              - 203.0.113.5/32
+              - 2001:db8::/32
+        ipDenyList:
+          type: array
+          maxItems: 200
+          description: |-
+            Source addresses refused even when `ipAllowList` permits them. Same entry
+            format and stored form as `ipAllowList`; deny always wins over allow.
+          items:
+            type: string
+          examples:
+            - - 198.51.100.0/24
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the policy was created.
+          examples:
+            - '2026-09-22T03:24:49.115Z'
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the policy was last modified. Updated on every PUT and PATCH that changes a field.
+          examples:
+            - '2026-09-22T03:27:28.318Z'
+    Error:
+      type: object
+      description: Standard error response envelope returned by integrator.io APIs.
+      properties:
+        errors:
+          type: array
+          description: List of errors that occurred while processing the request.
+          items:
+            type: object
+            properties:
+              code:
+                oneOf:
+                  - type: string
+                  - type: integer
+                description: |-
+                  Machine-readable error code. Usually a string like
+                  `invalid_ref`, `missing_required_field`, or `unauthorized`;
+                  may be an **integer** when the error mirrors an upstream HTTP
+                  status (e.g. `500`) — most commonly returned by connection-ping
+                  and adaptor-proxy responses.
+              message:
+                type: string
+                description: Human-readable description of the error.
+              field:
+                type: string
+                description: |-
+                  Optional pointer to the document field that caused the error.
+                  Used by structural validation errors (`missing_required_field`,
+                  `invalid_ref`) to indicate which field is at fault
+                  (e.g. `_id`, `type`, `http.baseURI`).
+              source:
+                type: string
+                description: |-
+                  Optional origin layer for the error — e.g. `application` when
+                  the error came from the remote system the adaptor called,
+                  `connector` when the adaptor itself rejected the request.
+            required:
+              - message
+      required:
+        - errors
+    Request:
+      type: object
+      description: Request body for creating or replacing a network policy.
+      x-celigo-ai-guidance:
+        - |-
+          Send `ipAllowList`, `ipDenyList`, and `description` on every PUT. A replace clears whatever
+          it omits — a rename that sends only `name` comes back with both lists empty and the
+          description gone, which silently removes every IP restriction the policy carried.
+        - |-
+          Write entries as IPv4 or IPv6 addresses or CIDR ranges; the server stores bare addresses as
+          `/32` or `/128`. Anything else — a hostname, an empty string, a number, a prefix longer than
+          the address family allows — fails with 400 `invalid_cidr`, and a list of more than 200
+          entries fails with 400 `max_cidr_entries_exceeded`. Duplicate entries are stored as sent.
+        - |-
+          `name` must be unique among the environment's live policies: a duplicate fails with 409
+          `conflict` on create, replace, and patch. A name held only by a policy in the recycle bin
+          can be reused.
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          maxLength: 150
+          description: Display name shown wherever a policy is picked or listed. Unique among the environment's policies that are not in the recycle bin.
+          x-celigo-ai-guidance:
+            - Name the policy after the network it describes ("Corporate VPN egress", "Partner SFTP host"), not after the token or MCP server it is assigned to — one policy can be assigned to many principals.
+          examples:
+            - Corporate VPN egress
+        description:
+          type: string
+          maxLength: 500
+          description: Explains what the policy is for and where its ranges come from. Omit on PUT to clear it.
+          examples:
+            - Office and VPN egress ranges. Deny beats allow.
+        ipAllowList:
+          type: array
+          maxItems: 200
+          description: |-
+            Source addresses permitted to connect. Each entry is an IPv4 or IPv6 address
+            or CIDR range; bare addresses are stored as `/32` or `/128`. Leave empty to
+            permit every address that `ipDenyList` does not block. Omitting the field on
+            PUT empties the list.
+          items:
+            type: string
+          examples:
+            - - 10.0.0.0/8
+              - 203.0.113.5
+              - 2001:db8::/32
+        ipDenyList:
+          type: array
+          maxItems: 200
+          description: |-
+            Source addresses refused even when `ipAllowList` permits them. Same entry
+            format as `ipAllowList`; deny always wins over allow. Omitting the field on
+            PUT empties the list.
+          items:
+            type: string
+          examples:
+            - - 198.51.100.0/24
+    NetworkPolicyDependencyRef:
+      type: object
+      description: A resource the policy is assigned to.
+      required:
+        - _id
+        - name
+      properties:
+        _id:
+          type: string
+          format: objectId
+          description: Identifier of the assigned resource; use it with the resource's own `GET /v1/<type>/{_id}` endpoint.
+          examples:
+            - 6ab1f4a95af4c5a3ea6b0a28
+        name:
+          type: string
+          description: Display name of the assigned resource at the time of the request.
+          examples:
+            - Order lookup MCP server
+    NetworkPolicyEnvironmentRef:
+      type: object
+      description: An environment whose sign-in the policy restricts.
+      required:
+        - _envUserId
+        - name
+      properties:
+        _envUserId:
+          type: string
+          format: objectId
+          x-celigo-refModel: users
+          description: Account user that represents the environment holding the assignment.
+          examples:
+            - 624cb0346309dc3a543733a2
+        name:
+          type:
+            - string
+            - 'null'
+          description: Environment name. Null when the environment has no name record, in which case identify it by `_envUserId`.
+          examples:
+            - Production
+    NetworkPolicyDependencies:
+      type: object
+      description: |-
+        Every place a network policy is assigned within its own environment. All four
+        keys are always present; an unassigned policy returns empty arrays and `false`
+        flags.
+      required:
+        - mcpservers
+        - accesstokens
+        - account
+      properties:
+        mcpservers:
+          type: array
+          description: MCP servers whose `_networkPolicyId` is this policy.
+          items:
+            $ref: '#/components/schemas/NetworkPolicyDependencyRef'
+        accesstokens:
+          type: array
+          description: API tokens whose `_networkPolicyId` is this policy. Personal access tokens never appear here; they inherit the account's workspace-user policy instead.
+          items:
+            $ref: '#/components/schemas/NetworkPolicyDependencyRef'
+        account:
+          type: object
+          description: Account sign-in assignments of this policy, resolved per environment.
+          required:
+            - workspaceUsers
+            - workspaceUserEnvironments
+            - endUsers
+            - endUserEnvironments
+          properties:
+            workspaceUsers:
+              type: boolean
+              description: When true, the policy restricts workspace-user sign-in in at least one environment listed in `workspaceUserEnvironments`.
+              examples:
+                - false
+            workspaceUserEnvironments:
+              type: array
+              description: Environments whose workspace-user sign-in this policy restricts. Empty when `workspaceUsers` is false.
+              items:
+                $ref: '#/components/schemas/NetworkPolicyEnvironmentRef'
+            endUsers:
+              type: boolean
+              description: When true, the policy restricts end-user sign-in in at least one environment listed in `endUserEnvironments`.
+              examples:
+                - false
+            endUserEnvironments:
+              type: array
+              description: Environments whose end-user sign-in this policy restricts. Empty when `endUsers` is false.
+              items:
+                $ref: '#/components/schemas/NetworkPolicyEnvironmentRef'
+    JsonPatchOperation:
+      type: object
+      description: A single JSON Patch operation (RFC 6902).
+      required:
+        - op
+        - path
+      properties:
+        op:
+          type: string
+          enum:
+            - replace
+            - add
+            - remove
+          x-enumDescriptions:
+            replace: Replaces the value at the specified path.
+            add: Sets the value at the specified path.
+            remove: Removes the value at the specified path.
+          description: The operation to perform.
+        path:
+          type: string
+          description: |-
+            JSON Pointer (RFC 6901) to the field to patch. Only
+            whitelisted paths are accepted — unlisted paths return
+            `422` with `"<path> is not a whitelisted property"`.
+        value:
+          description: The new value to set. Required for `replace` and `add`, omit for `remove`.
+    JsonPatchRequest:
+      type: array
+      description: |-
+        A JSON Patch document (RFC 6902). Send an array of patch
+        operations on whitelisted fields — all other paths are rejected
+        with 422.
+      minItems: 1
+      items:
+        $ref: '#/components/schemas/JsonPatchOperation'
+  responses:
+    400-bad-request:
+      description: |
+        Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: invalid_request
+                    message: The request body failed validation.
+    401-unauthorized:
+      description: |-
+        Unauthorized. The request lacks a valid bearer token, or the provided token
+        failed to authenticate.
+
+        Note: the 401 response is produced by the auth middleware **before** the
+        request reaches the endpoint handler, so it does **not** follow the
+        standard `{errors: [...]}` envelope. Instead the body is a bare
+        `{message: string}` object with no `code`, no `errors` array. Callers
+        handling 401s should key off the HTTP status and the `message` string,
+        not try to destructure an `errors[]`.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                description: |-
+                  Human-readable description of the auth failure. Known values:
+                  - `"Unauthorized"` — no `Authorization` header on the request.
+                  - `"Bearer Authentication Failed"` — header present but token
+                    is invalid, revoked, or expired.
+            required:
+              - message
+          examples:
+            missing_token:
+              summary: No Authorization header sent
+              value:
+                message: Unauthorized
+            invalid_token:
+              summary: Bearer token invalid or revoked
+              value:
+                message: Bearer Authentication Failed
+    422-unprocessable-entity:
+      description: |
+        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: unprocessable_entity
+                    message: The request could not be processed due to a semantic error.
+    409-name-conflict:
+      description: |-
+        Conflict. Another policy in this environment that is not in the recycle bin
+        already uses the requested `name`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: conflict
+                    message: A network policy with this name already exists in the account.
+    404-not-found:
+      description: |
+        Not found. The requested resource does not exist or is not visible to the caller.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: not_found
+                    message: The requested resource was not found.
+    409-in-use:
+      description: |-
+        Conflict. The policy is still assigned to at least one API token, MCP server, or
+        account sign-in setting, so it was not deleted. `info` lists every assignment;
+        repeat the request with `force=true` to clear them and delete the policy.
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: '#/components/schemas/Error'
+              - type: object
+                properties:
+                  info:
+                    $ref: '#/components/schemas/NetworkPolicyDependencies'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: network_policy_in_use
+                    message: This policy is assigned to 2 resources. Deleting it removes those restrictions.
+                info:
+                  mcpservers:
+                    - _id: 6ab1f4a95af4c5a3ea6b0a28
+                      name: Order lookup MCP server
+                  accesstokens:
+                    - _id: 6ab1f6a338d7733b4599ec83
+                      name: Warehouse sync token
+                  account:
+                    workspaceUsers: false
+                    workspaceUserEnvironments: []
+                    endUsers: false
+                    endUserEnvironments: []
+x-internal: false
+x-enable-proxy: true