aspera-cli 4.27.5 → 4.28.0

data/lib/aspera/schema/IBM Aspera faspio Gateway API-1.0.0-enhanced.yaml

@@ -0,0 +1,1097 @@
+# DO NOT EDIT THIS FILE MANUALLY
+# This file is automatically downloaded from:
+# https://raw.githubusercontent.com/laurent-martin/aspera-api-examples/refs/heads/main/openapi/IBM%20Aspera%20faspio%20Gateway%20API-1.0.0-enhanced.yaml
+# Use 'rake tools:openapi' to update this file
+
+openapi: 3.1.0
+info:
+  title: IBM Aspera faspio Gateway API
+  description: |
+    REST API for managing IBM Aspera faspio Gateway bridges and monitoring.
+
+    ## Overview
+    IBM Aspera faspio Gateway bridges local TCP or UDP connections over the FASP (Fast, Adaptive, and Secure Protocol)
+    transport to a remote gateway peer. You can use this API to create, inspect, and delete **dynamic**
+    bridges at runtime without restarting the gateway.
+
+    Static bridges (defined in `gateway.toml`) are read-only via this API — they can be retrieved
+    but cannot be deleted or modified.
+
+    ## Authentication
+    The API supports three authentication modes, configured in `gateway.toml` under `[admin]`:
+
+    | Mode | Description |
+    |------|-------------|
+    | `none` | No authentication (development only) |
+    | `basic` | HTTP Basic Authentication (username + SHA-512/PBKDF2 password digest) |
+    | `oauth2` | Bearer JWT token obtained via `POST /auth/token` |
+
+    ## OAuth 2.0 quick start
+
+    This gateway implements the **JWT Bearer grant** (RFC 7523). There is no identity provider
+    involved — the gateway itself issues and verifies tokens using RSA key pairs you generate.
+
+    ### Step 1 — Generate key pairs
+
+    The gateway needs **two** RSA key pairs:
+
+    | Key pair | Who holds it | Purpose |
+    |----------|-------------|---------|
+    | **Client key pair** | Your application | Sign JWT assertions sent to `POST /auth/token` |
+    | **Server key pair** | The gateway | Sign access tokens returned to your application |
+
+    ```bash
+    # Client key pair (your application uses the private key to sign assertions)
+    openssl genrsa -out client_private.pem 2048
+    openssl rsa -in client_private.pem -pubout -out client_public.pem
+
+    # Server key pair (the gateway uses the private key to sign access tokens)
+    openssl genrsa -out server_private.pem 2048
+    openssl rsa -in server_private.pem -pubout -out server_public.pem
+    ```
+
+    ### Step 2 — Configure `gateway.toml`
+
+    Give the gateway the **client's public key** (to verify assertions) and the
+    **server's private key** (to sign access tokens):
+
+    ```toml
+    [admin]
+    rest_api_auth = "oauth2"
+    rest_api_enabled = true
+
+    [admin.oauth2]
+    client_id            = "my-gateway-client"
+    jwt_grant_enabled    = true
+    jwt_verification_key = "/etc/faspio-gateway/client_public.pem"   # verifies your assertion
+    jwt_signing_key      = "/etc/faspio-gateway/server_private.pem"  # signs the access token
+    ```
+
+    ### Step 3 — Create a JWT assertion
+
+    Your application signs a short-lived JWT with its **private key**.
+    The `iss` and `sub` claims must both equal the `client_id` in `gateway.toml`.
+
+    Example using Python (PyJWT):
+    ```python
+    import jwt, time
+
+    with open("client_private.pem") as f:
+        private_key = f.read()
+
+    assertion = jwt.encode(
+        {"iss": "my-gateway-client", "sub": "my-gateway-client",
+         "exp": int(time.time()) + 300},   # valid for 5 minutes
+        private_key,
+        algorithm="RS256"
+    )
+    ```
+
+    Example using `openssl` + `bash` (no extra libraries):
+    ```bash
+    HEADER=$(echo -n '{"alg":"RS256","typ":"JWT"}' | base64url)
+    NOW=$(date +%s); EXP=$((NOW + 300))
+    PAYLOAD=$(echo -n "{\"iss\":\"my-gateway-client\",\"sub\":\"my-gateway-client\",\"exp\":$EXP}" | base64url)
+    SIG=$(echo -n "$HEADER.$PAYLOAD" | openssl dgst -sha256 -sign client_private.pem | base64url)
+    ASSERTION="$HEADER.$PAYLOAD.$SIG"
+    ```
+
+    ### Step 4 — Exchange the assertion for an access token
+
+    ```bash
+    curl -s -X POST http://127.0.0.1:8080/auth/token \
+      -H "Content-Type: application/json" \
+      -d "{\"grant_type\":\"urn:ietf:params:oauth:grant-type:jwt-bearer\",
+           \"assertion\":\"$ASSERTION\",
+           \"client_id\":\"my-gateway-client\"}"
+    ```
+
+    Response:
+    ```json
+    {
+      "access_token": "<TOKEN>",
+      "token_type": "Bearer",
+      "expires_in": 3600
+    }
+    ```
+
+    ### Step 5 — Call the API with the access token
+
+    ```bash
+    TOKEN="<TOKEN>"
+
+    # List all bridges
+    curl -s http://127.0.0.1:8080/bridges \
+      -H "Authorization: Bearer $TOKEN"
+
+    # Create a bridge
+    curl -s -X POST http://127.0.0.1:8080/bridges \
+      -H "Authorization: Bearer $TOKEN" \
+      -H "Content-Type: application/json" \
+      -d '{"name":"Bridge-1","local":{"bind_address":"127.0.0.1","port":"2000","protocol":"tcp","tls_enabled":false},"forward":{"host":["10.0.0.2"],"port":"3000","protocol":"fasp","tls_enabled":false}}'
+    ```
+
+    The access token expires after **1 hour** (`expires_in: 3600`). Repeat steps 3–4 to renew it.
+
+    ## Bridge lifecycle
+    ```text
+    POST /bridges
+        ↓
+    (bridge created and started)
+        ↓
+    GET /bridges/{id}
+        ↓
+    DELETE /bridges/{id}
+        ↓
+    (bridge stopped and removed)
+    ```
+
+    Bridges created via the API are **dynamic** — they are persisted to a runtime state file
+    and survive gateway restarts.
+  contact:
+    name: IBM Aspera Support
+    email: Aspera-client-team@wwpdl.vnet.ibm.com
+  license:
+    name: © IBM. All rights reserved
+    url: https://www-40.ibm.com/software/sla/sladb.nsf/displaylis/0CF8A1C0BA2B994C002587F70069A8B5?OpenDocument
+  version: 1.0.0
+servers:
+  - url: http://127.0.0.1:8080
+    description: Default local gateway admin endpoint (HTTP)
+  - url: https://127.0.0.1:8080
+    description: Default local gateway admin endpoint (HTTPS/TLS)
+paths:
+  # ---------------------------------------------------------------------------
+  # Health
+  # ---------------------------------------------------------------------------
+  /ping:
+    get:
+      operationId: ping
+      summary: Liveness probe
+      description: |
+        Returns an empty JSON object `{}` when the gateway HTTP server is running.
+        This endpoint does **not** require authentication and is not subject to the
+        configured `rest_api_auth` scheme — it can be used by load balancers and
+        orchestrators for health checks.
+      # Note: /ping is intentionally unauthenticated — no 4xx responses apply.
+      # The linter warning `operation-4xx-response` is suppressed by design.
+      responses:
+        '200':
+          description: The gateway is running.
+          headers:
+            Cache-Control:
+              description: Always `no-cache` — do not cache liveness responses.
+              schema:
+                type: string
+                examples:
+                  - no-cache
+          content:
+            application/json:
+              schema:
+                description: Empty JSON object.
+                type: object
+                examples:
+                  - {}
+      security: [] # Explicitly unauthenticated
+      tags:
+        - Health
+    options:
+      tags:
+        - Health
+      summary: CORS preflight for /ping
+      description: Handles browser CORS preflight requests for the `/ping` endpoint.
+      operationId: pingOptions
+      security: []
+      # Note: OPTIONS preflight responses never return 4xx by CORS spec design.
+      responses:
+        '204':
+          description: No Content — CORS headers returned.
+          headers:
+            Access-Control-Allow-Origin:
+              schema:
+                type: string
+                examples:
+                  - '*'
+            Access-Control-Allow-Methods:
+              schema:
+                type: string
+                examples:
+                  - DELETE, GET, PUT, POST
+            Access-Control-Allow-Headers:
+              schema:
+                type: string
+                examples:
+                  - Authorization, Content-Type
+  # ---------------------------------------------------------------------------
+  # Bridges — collection
+  # ---------------------------------------------------------------------------
+  /bridges:
+    get:
+      operationId: getBridges
+      summary: List all bridges
+      description: |
+        Returns an array of all configured bridges — both **static** (from `gateway.toml`)
+        and **dynamic** (created via `POST /bridges`).
+
+        An empty gateway returns `[]`.
+      responses:
+        '200':
+          description: Array of bridge configurations (may be empty).
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/BridgeResponse'
+              examples:
+                empty:
+                  summary: No bridges configured
+                  value: []
+                single_tcp_fasp:
+                  summary: One TCP→FASP bridge
+                  value:
+                    - id: '1'
+                      name: Bridge-1
+                      source: dynamic
+                      local:
+                        bind_address: 127.0.0.1
+                        port:
+                          - 2000
+                          - 2001
+                        protocol: tcp
+                        tls_enabled: false
+                      forward:
+                        host:
+                          - gw2.example.com
+                          - 10.0.0.2
+                        port:
+                          - 3000
+                          - 3001
+                        protocol: fasp
+                        tls_enabled: false
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+      tags:
+        - Bridges
+    post:
+      operationId: createBridge
+      summary: Create a new bridge
+      description: |
+        Creates a new **dynamic** bridge, starts it immediately, and persists it to the
+        runtime state file so it survives a gateway restart.
+
+        ### Port syntax
+        The `port` field of the request body accepts either:
+        - A single port number as a string: `"2000"`
+        - A contiguous range: `"2000-2003"` (expands to ports 2000, 2001, 2002, 2003)
+
+        ### Protocol combinations
+        | Local protocol | Forward protocol | Description |
+        |---------------|-----------------|-------------|
+        | `tcp`         | `fasp`          | Most common: accelerate TCP over FASP |
+        | `udp`         | `fasp`          | Accelerate UDP over FASP |
+        | `tcp`         | `tcp`           | TCP relay (no acceleration) |
+        | `udp`         | `udp`           | UDP relay |
+
+        ### Static bridge limitation
+        This endpoint only creates dynamic bridges. Static bridges defined in `gateway.toml`
+        cannot be created via the API.
+      requestBody:
+        description: Bridge configuration to create.
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/BridgeRequest'
+            examples:
+              tcp_to_fasp:
+                summary: Forward local TCP traffic over FASP
+                value:
+                  name: Bridge-1
+                  local:
+                    bind_address: 127.0.0.1
+                    port: 2000-2001
+                    protocol: tcp
+                    tls_enabled: false
+                  forward:
+                    host:
+                      - gw2.example.com
+                      - 10.0.0.2
+                    port: 3000-3001
+                    protocol: fasp
+                    tls_enabled: false
+              udp_to_fasp:
+                summary: Forward local UDP traffic over FASP
+                value:
+                  name: Bridge-UDP
+                  local:
+                    bind_address: 0.0.0.0
+                    port: '4000'
+                    protocol: udp
+                    tls_enabled: false
+                  forward:
+                    host:
+                      - 10.0.0.2
+                    port: '5000'
+                    protocol: fasp
+                    tls_enabled: true
+      responses:
+        '201':
+          description: Bridge created and started successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BridgeResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '415':
+          $ref: '#/components/responses/UnsupportedMediaType'
+        '422':
+          $ref: '#/components/responses/UnprocessableEntity'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+      tags:
+        - Bridges
+    options:
+      tags:
+        - Bridges
+      summary: CORS preflight for /bridges
+      operationId: bridgesOptions
+      security: []
+      # Note: OPTIONS preflight responses never return 4xx by CORS spec design.
+      responses:
+        '204':
+          description: No Content — CORS headers returned.
+  # ---------------------------------------------------------------------------
+  # Bridges — single resource
+  # ---------------------------------------------------------------------------
+  /bridges/{id}:
+    parameters:
+      - $ref: '#/components/parameters/BridgeId'
+    get:
+      operationId: getBridgeById
+      summary: Get a bridge by ID
+      description: |
+        Returns the full configuration of a single bridge identified by `id`.
+        Works for both static and dynamic bridges.
+      responses:
+        '200':
+          description: Bridge configuration.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BridgeResponse'
+              example:
+                id: '1'
+                name: Bridge-1
+                source: dynamic
+                local:
+                  bind_address: 127.0.0.1
+                  port:
+                    - 2000
+                    - 2001
+                  protocol: tcp
+                  tls_enabled: false
+                forward:
+                  host:
+                    - gw2.example.com
+                  port:
+                    - 3000
+                    - 3001
+                  protocol: fasp
+                  tls_enabled: false
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      tags:
+        - Bridges
+    delete:
+      operationId: deleteBridgeById
+      summary: Delete a bridge
+      description: |
+        Stops and removes a **dynamic** bridge by its `id`.
+
+        - Returns `204 No Content` on success.
+        - Returns `403 Forbidden` if the bridge is **static** (defined in `gateway.toml`) —
+          static bridges cannot be deleted via the API; edit the configuration file instead.
+        - Returns `404 Not Found` if no bridge with the given `id` exists.
+      responses:
+        '204':
+          description: Bridge stopped and deleted successfully. No response body.
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+      tags:
+        - Bridges
+    put:
+      operationId: updateBridgeById
+      summary: Update a bridge (not yet implemented)
+      description: |
+        **Not implemented.** Reserved for future use.
+
+        When implemented, this endpoint will update only **dynamic** bridges.
+        Attempting to update a **static** bridge will return `403 Forbidden`.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/BridgeRequest'
+      # Note: PUT is not yet implemented — no 2xx response exists by design.
+      # The linter warning `operation-2xx-response` is suppressed by design.
+      responses:
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '501':
+          description: Not Implemented — this endpoint is reserved for a future release.
+      tags:
+        - Bridges
+    options:
+      tags:
+        - Bridges
+      summary: CORS preflight for /bridges/{id}
+      operationId: bridgeByIdOptions
+      security: []
+      # Note: OPTIONS preflight responses never return 4xx by CORS spec design.
+      responses:
+        '204':
+          description: No Content — CORS headers returned.
+  # ---------------------------------------------------------------------------
+  # OAuth 2.0 token endpoint
+  # ---------------------------------------------------------------------------
+  /auth/token:
+    post:
+      operationId: createAccessToken
+      summary: Request an OAuth 2.0 access token
+      description: |
+        Issues a signed JWT access token using the
+        **JWT Bearer grant type** (`urn:ietf:params:oauth:grant-type:jwt-bearer`).
+
+        The client must supply a signed JWT assertion (signed with the client's private RSA key).
+        The gateway verifies the assertion against the configured `jwt_verification_key`, then
+        issues a short-lived RS256-signed JWT (default: 1 hour) signed with `jwt_signing_key`.
+
+        Supports two content types:
+        - `application/json` — fields as a JSON object body
+        - `application/x-www-form-urlencoded` — fields as URL-encoded form body
+
+        This endpoint is only available when `rest_api_auth = "oauth2"` is configured in
+        `gateway.toml`. It does **not** require a bearer token itself.
+
+        ### JWT assertion requirements
+        The JWT assertion must contain:
+        - `iss` (issuer): the `client_id` configured in `gateway.toml`
+        - `sub` (subject): the `client_id` configured in `gateway.toml`
+        - `exp` (expiration): a future timestamp
+
+        The signature must be verifiable with the public key at `jwt_verification_key`.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TokenRequest'
+            example:
+              grant_type: urn:ietf:params:oauth:grant-type:jwt-bearer
+              assertion: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
+              client_id: my-gateway-client
+          application/x-www-form-urlencoded:
+            schema:
+              $ref: '#/components/schemas/TokenRequest'
+      responses:
+        '200':
+          description: Access token issued successfully.
+          headers:
+            Cache-Control:
+              description: Always `no-cache`.
+              schema:
+                type: string
+                examples:
+                  - no-cache
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TokenResponse'
+        '400':
+          description: |
+            Bad Request — the `grant_type` is not `urn:ietf:params:oauth:grant-type:jwt-bearer`,
+            the `assertion` field is empty, or required fields are missing.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: |
+            Unauthorized — the JWT assertion failed verification (bad signature, wrong issuer/subject,
+            expired token, or missing `exp` claim).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '415':
+          $ref: '#/components/responses/UnsupportedMediaType'
+        '422':
+          $ref: '#/components/responses/UnprocessableEntity'
+      security: [] # Token endpoint itself is unauthenticated
+      tags:
+        - Auth
+  # ---------------------------------------------------------------------------
+  # Prometheus metrics
+  # ---------------------------------------------------------------------------
+  /metrics:
+    get:
+      operationId: getMetrics
+      summary: Prometheus metrics
+      description: |
+        Returns Prometheus-format metrics for all bridges managed by this gateway instance.
+
+        Supports gzip compression: include `Accept-Encoding: gzip` in the request to receive
+        a compressed response (the response will include `Content-Encoding: gzip`).
+
+        This endpoint is only exposed when `prometheus_enabled = true` in `gateway.toml`.
+        It can optionally require HTTP Basic authentication (`prometheus_auth = "basic"`).
+      parameters:
+        - name: Accept-Encoding
+          in: header
+          description: Set to `gzip` to receive a compressed response.
+          required: false
+          schema:
+            type: string
+            examples:
+              - gzip
+      responses:
+        '200':
+          description: Prometheus text exposition format (OpenMetrics 0.0.4 compatible).
+          headers:
+            Content-Encoding:
+              description: Present with value `gzip` when compression was requested and
+                applied.
+              schema:
+                type: string
+                examples:
+                  - gzip
+          content:
+            text/plain:
+              schema:
+                description: Prometheus text exposition format, version 0.0.4.
+                type: string
+                examples:
+                  - |
+                    # HELP faspio_bridge_sessions_total Total number of sessions
+                    # TYPE faspio_bridge_sessions_total counter
+                    faspio_bridge_sessions_total{bridge="Bridge-1"} 42
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+      tags:
+        - Metrics
+# =============================================================================
+# Components
+# =============================================================================
+components:
+  # ---------------------------------------------------------------------------
+  # Parameters
+  # ---------------------------------------------------------------------------
+  parameters:
+    BridgeId:
+      name: id
+      in: path
+      required: true
+      description: |
+        Unique identifier of the bridge. Bridge IDs are assigned by the gateway at creation time
+        and are stable for the lifetime of the gateway process.
+      schema:
+        type: string
+        examples:
+          - '1'
+  # ---------------------------------------------------------------------------
+  # Schemas
+  # ---------------------------------------------------------------------------
+  schemas:
+    # ------------------------------------------------------------------
+    # Enumerations (extracted from bridge_config.hpp / rest_api.cpp)
+    # ------------------------------------------------------------------
+
+    Protocol:
+      description: |
+        Transport protocol used on an abutment:
+        - `tcp`: Transmission Control Protocol (reliable, ordered byte stream)
+        - `udp`: User Datagram Protocol (unreliable, connectionless datagrams)
+        - `fasp`: IBM Aspera FASP (reliable high-speed UDP-based transfer protocol)
+      type: string
+      examples:
+        - fasp
+      enum:
+        - tcp
+        - udp
+        - fasp
+    BridgeSource:
+      description: |
+        Indicates the origin of a bridge configuration.
+
+        | Value     | Description |
+        |-----------|-------------|
+        | `static`  | Loaded from `gateway.toml` at startup. Read-only via the API — cannot be deleted or updated. |
+        | `dynamic` | Created at runtime via `POST /bridges`. Mutable and persisted to the runtime state file. |
+      type: string
+      examples:
+        - dynamic
+      enum:
+        - static
+        - dynamic
+    # ------------------------------------------------------------------
+    # Port representation
+    # ------------------------------------------------------------------
+
+    PortList:
+      description: |
+        Expanded list of port numbers (integers) as returned by the API.
+        A request range `"2000-2002"` is expanded to `[2000, 2001, 2002]`.
+      type: array
+      items:
+        type: integer
+        format: int32
+        minimum: 1
+        maximum: 65535
+      examples:
+        - - 2000
+          - 2001
+      minItems: 1
+    PortRange:
+      description: |
+        Port or port range string as accepted in request bodies.
+
+        - Single port: `"2000"`
+        - Contiguous range: `"2000-2003"` (inclusive, expands to 4 ports)
+
+        Port numbers must be between 1 and 65535.
+      type: string
+      examples:
+        - 2000-2001
+      pattern: ^\d{1,5}(-\d{1,5})?$
+    # ------------------------------------------------------------------
+    # Abutment schemas (request / response split)
+    # ------------------------------------------------------------------
+
+    LocalAbutmentRequest:
+      description: |
+        Configuration of the **local** abutment — the side that accepts incoming connections
+        on this gateway node.
+      type: object
+      properties:
+        bind_address:
+          description: |
+            IP address or hostname that the local abutment binds to.
+            Use `"0.0.0.0"` to listen on all interfaces.
+          type: string
+          examples:
+            - 127.0.0.1
+        port:
+          $ref: '#/components/schemas/PortRange'
+        protocol:
+          description: |
+            Protocol accepted on the local side. Typically `tcp` or `udp`.
+          example: tcp
+          $ref: '#/components/schemas/Protocol'
+        tls_enabled:
+          description: |
+            When `true`, the local abutment expects TLS-wrapped connections.
+            Requires `tls_certificate`, `cert_key` (or a combined `cert_chain`) to be
+            configured in `gateway.toml`.
+          type: boolean
+          examples:
+            - false
+      required:
+        - bind_address
+        - port
+        - protocol
+        - tls_enabled
+    ForwardAbutmentRequest:
+      description: |
+        Configuration of the **forward** abutment — the side that establishes outgoing connections
+        to the remote gateway peer.
+      type: object
+      properties:
+        host:
+          description: |
+            One or more hostnames or IP addresses of the remote peer gateway.
+            When multiple hosts are specified, the gateway will attempt each in order as a fallback
+            (first host is the primary; remaining hosts are used if the primary is unreachable).
+          type: array
+          items:
+            type: string
+          examples:
+            - - gw2.example.com
+              - 10.0.0.2
+          minItems: 1
+        bind_address:
+          description: |
+            Optional local IP address to bind the outgoing connection to.
+            When omitted, the OS selects the source address automatically.
+          type: string
+          examples:
+            - 192.168.1.10
+        port:
+          $ref: '#/components/schemas/PortRange'
+        protocol:
+          description: |
+            Protocol used to connect to the remote peer. Typically `fasp` for acceleration.
+          example: fasp
+          $ref: '#/components/schemas/Protocol'
+        tls_enabled:
+          description: |
+            When `true`, the outgoing connection to the remote peer is TLS-wrapped.
+          type: boolean
+          examples:
+            - false
+      required:
+        - host
+        - port
+        - protocol
+        - tls_enabled
+    LocalAbutmentResponse:
+      description: Local abutment as returned by the API (ports expanded to an integer
+        array).
+      type: object
+      properties:
+        bind_address:
+          type: string
+          examples:
+            - 127.0.0.1
+        port:
+          $ref: '#/components/schemas/PortList'
+        protocol:
+          $ref: '#/components/schemas/Protocol'
+        tls_enabled:
+          type: boolean
+          examples:
+            - false
+      required:
+        - bind_address
+        - port
+        - protocol
+        - tls_enabled
+    ForwardAbutmentResponse:
+      description: Forward abutment as returned by the API (ports expanded to an
+        integer array).
+      type: object
+      properties:
+        bind_address:
+          description: Local bind address for the outgoing connection, if configured.
+          type: string
+          examples:
+            - 192.168.1.10
+        host:
+          description: List of remote peer hostnames / IP addresses.
+          type: array
+          items:
+            type: string
+          examples:
+            - - gw2.example.com
+              - 10.0.0.2
+        port:
+          $ref: '#/components/schemas/PortList'
+        protocol:
+          $ref: '#/components/schemas/Protocol'
+        tls_enabled:
+          type: boolean
+          examples:
+            - false
+      required:
+        - host
+        - port
+        - protocol
+        - tls_enabled
+    # ------------------------------------------------------------------
+    # Bridge schemas
+    # ------------------------------------------------------------------
+
+    BridgeRequest:
+      description: |
+        Payload for creating a new bridge via `POST /bridges`.
+
+        The gateway generates the `id` automatically. The `source` field is always set to
+        `dynamic` for bridges created via the API.
+      type: object
+      properties:
+        name:
+          description: |
+            Human-readable label for the bridge. Does not have to be unique,
+            but a descriptive name helps with monitoring and troubleshooting.
+          type: string
+          examples:
+            - Bridge-1
+          minLength: 1
+        local:
+          $ref: '#/components/schemas/LocalAbutmentRequest'
+        forward:
+          $ref: '#/components/schemas/ForwardAbutmentRequest'
+      required:
+        - name
+        - local
+        - forward
+    BridgeResponse:
+      description: Full bridge configuration as returned by `GET /bridges` and `GET
+        /bridges/{id}`.
+      type: object
+      properties:
+        id:
+          description: |
+            Gateway-assigned unique identifier for this bridge.
+            Stable for the lifetime of the gateway process.
+          type: string
+          examples:
+            - '1'
+        name:
+          description: Human-readable label for the bridge.
+          type: string
+          examples:
+            - Bridge-1
+        source:
+          $ref: '#/components/schemas/BridgeSource'
+        local:
+          $ref: '#/components/schemas/LocalAbutmentResponse'
+        forward:
+          $ref: '#/components/schemas/ForwardAbutmentResponse'
+      required:
+        - id
+        - name
+        - source
+        - local
+        - forward
+    # ------------------------------------------------------------------
+    # OAuth 2.0
+    # ------------------------------------------------------------------
+
+    TokenRequest:
+      description: OAuth 2.0 token request body (JWT Bearer grant).
+      type: object
+      properties:
+        grant_type:
+          description: |
+            Must be `urn:ietf:params:oauth:grant-type:jwt-bearer` (RFC 7523).
+          type: string
+          examples:
+            - urn:ietf:params:oauth:grant-type:jwt-bearer
+          const: urn:ietf:params:oauth:grant-type:jwt-bearer
+        assertion:
+          description: |
+            A signed JWT (JWS) assertion issued by the client.
+
+            The JWT must contain:
+            - `iss`: the `client_id` configured in `gateway.toml`
+            - `sub`: the `client_id` configured in `gateway.toml`
+            - `exp`: a future expiry timestamp
+
+            The signature must be an RS256 signature verifiable with the public key
+            at `jwt_verification_key` in `gateway.toml`.
+          type: string
+          examples:
+            - eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJteS1jbGllbnQiLCJzdWIiOiJteS1jbGllbnQiLCJleHAiOjE3MDAwMDAwMDB9.signature
+        client_id:
+          description: |
+            Optional. The OAuth 2.0 client identifier. When provided, it is validated
+            against the `client_id` value in `gateway.toml`. If omitted, the `iss`/`sub`
+            claims of the assertion are used for validation.
+          type: string
+          examples:
+            - my-gateway-client
+      required:
+        - grant_type
+        - assertion
+    TokenResponse:
+      description: Successful OAuth 2.0 token response.
+      type: object
+      properties:
+        access_token:
+          description: |
+            RS256-signed JWT access token. Include this in the `Authorization: Bearer <token>`
+            header for subsequent API calls.
+          type: string
+          examples:
+            - eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
+        token_type:
+          description: Always `Bearer`.
+          type: string
+          examples:
+            - Bearer
+          const: Bearer
+        expires_in:
+          description: Token lifetime in seconds. Default is 3600 (1 hour).
+          type: integer
+          format: int64
+          examples:
+            - 3600
+      required:
+        - access_token
+        - token_type
+        - expires_in
+    # ------------------------------------------------------------------
+    # Error schema
+    # ------------------------------------------------------------------
+
+    ErrorResponse:
+      description: |
+        Generic error response body. Not all error responses include a body —
+        some HTTP status codes (for example, 204, 404) may return no content.
+      type: object
+      properties:
+        message:
+          description: Human-readable error description.
+          type: string
+          examples:
+            - bridge not found
+      required:
+        - message
+  # ---------------------------------------------------------------------------
+  # Reusable responses
+  # ---------------------------------------------------------------------------
+  responses:
+    BadRequest:
+      description: |
+        Bad Request — the request could not be parsed or the path parameter is invalid.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            message: invalid bridge id
+    Unauthorized:
+      description: |
+        Unauthorized — no credentials were provided, or the provided credentials are invalid.
+
+        The response includes a `WWW-Authenticate` header indicating the expected scheme:
+        - Basic auth: `WWW-Authenticate: Basic realm="faspio Gateway API", charset="utf-8"`
+        - Bearer auth: `WWW-Authenticate: Bearer realm="Bridges", charset="utf-8"`
+      headers:
+        WWW-Authenticate:
+          schema:
+            type: string
+          example: Basic realm="faspio Gateway API", charset="utf-8"
+      content:
+        text/plain:
+          schema:
+            type: string
+          example: Unauthorized
+    Forbidden:
+      description: |
+        Forbidden — the operation is not permitted on this resource.
+        This is returned when attempting to delete or update a **static** bridge
+        (one loaded from `gateway.toml`). Static bridges are immutable via the API.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            message: cannot delete static bridge via REST API
+    NotFound:
+      description: Not Found — no bridge with the given `id` exists.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            message: bridge not found
+    UnsupportedMediaType:
+      description: |
+        Unsupported Media Type — the `Content-Type` header is missing or not
+        `application/json` (or `application/x-www-form-urlencoded` for the token endpoint).
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            message: Content-Type must be application/json
+    UnprocessableEntity:
+      description: |
+        Unprocessable Entity — the request body is syntactically valid JSON but
+        semantically incorrect (for example, a required field is missing, an enum value is
+        unrecognized, or a port range is malformed).
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            message: "JSON parse error: [json.exception.out_of_range.403] key 'name' not
+              found"
+    InternalServerError:
+      description: Internal Server Error — an unexpected error occurred in the gateway.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            message: unexpected error creating bridge
+  # ---------------------------------------------------------------------------
+  # Security schemes
+  # ---------------------------------------------------------------------------
+  securitySchemes:
+    basicAuth:
+      type: http
+      scheme: basic
+      description: |
+        HTTP Basic Authentication. The password is stored as a SHA-512 or PBKDF2 digest
+        in `gateway.toml` under `[admin.basic_auth]`. Configure with:
+        ```toml
+        [admin]
+        rest_api_auth = "basic"
+        [admin.basic_auth]
+        username = "admin"
+        password_digest = "<sha512-or-pbkdf2-hash>"
+        ```
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: |
+        OAuth 2.0 Bearer token (RS256-signed JWT). Obtain a token from `POST /auth/token`
+        using the JWT Bearer grant type. Configure the gateway with:
+        ```toml
+        [admin]
+        rest_api_auth = "oauth2"
+        [admin.oauth2]
+        client_id            = "my-gateway-client"
+        jwt_grant_enabled    = true
+        jwt_verification_key = "/etc/faspio-gateway/client_public.pem"
+        jwt_signing_key      = "/etc/faspio-gateway/server_private.pem"
+        ```
+tags:
+  - name: Health
+    description: Liveness probe — verify that the gateway process is reachable.
+  - name: Bridges
+    description: |
+      Create and manage network bridges.
+      A **bridge** is a bidirectional pipe that accepts connections on a local abutment (TCP or UDP)
+      and forwards them to a remote peer via a forward abutment (FASP, TCP, or UDP).
+  - name: Auth
+    description: |
+      OAuth 2.0 token endpoint. Only available when `rest_api_auth = "oauth2"` is set in `gateway.toml`.
+      Uses the JWT Bearer grant type (`urn:ietf:params:oauth:grant-type:jwt-bearer`).
+  - name: Metrics
+    description: |
+      Prometheus-compatible metrics endpoint. Only available when `prometheus_enabled = true`
+      in `gateway.toml`. Supports gzip compression via `Accept-Encoding: gzip`.
+externalDocs:
+  description: IBM Aspera faspio Gateway — Official Documentation
+  url: https://www.ibm.com/docs/en/faspio-gateway
+security:
+  - basicAuth: []
+  - bearerAuth: []
+  - {}