Fluence SecurityGroup API

openapi: 3.1.0
info:
  title: Fluence Billing SecurityGroup API
  description: "# Introduction\n\nThe Fluence API gives programmatic access to the decentralized Fluence compute marketplace, letting you find, rent, and\nmanage compute resources without the web UI. Integrate Fluence directly into your applications and automated workflows.\n\nBase URL: `https://api.fluence.dev`\n\nThe documentation starts with a high-level overview of design and technology, followed by endpoint reference details.\nFor additional user guides, see the [Fluence Documentation](https://fluence.dev/docs/build/overview).\n\n## Requests\n\nSend HTTPS requests to the Fluence API. All request and response bodies are JSON.\n\n- Set `Content-Type: application/json` for POST, PUT, and PATCH calls.\n- All examples assume the default `Accept: application/json` header.\n\n### Example\n\n```bash\ncurl -X POST https://api.fluence.dev/v1/public_ips \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: X-API-KEY <YOUR_API_KEY>\" \\\n  -d '{\n        \"addressType\": \"V4\",\n        \"clusterId\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n        \"name\": \"my-public-ip\"\n      }'\n```\n\n### HTTP request methods\n\nThe interface responds to different methods depending on the action required.\n\n| Method | Description                                                                                        |\n|--------|----------------------------------------------------------------------------------------------------|\n| GET    | Retrieves resource information. These requests are read-only and won't modify any resources.       |\n| POST   | Usually used to create new resources. Include all required attributes in the request body as JSON. |\n| PATCH  | Update specific attributes of a resource.                                                          |\n| PUT    | Updates an entire resource by replacing it with the provided data, regardless of current values.   |\n| DELETE | Removes resources.                                                                                 |\n\n## Responses\n\nSuccessful requests return `2xx` status codes and a JSON object.   \n\nIf an error occurs, Fluence returns an `4xx` or `5xx` status code and a JSON object describing the problem.\n\n### Response codes\n\n| Code | Description                                                                    |\n|------|--------------------------------------------------------------------------------|\n| 2xx  | **Success** - The request was successfully received, understood, and processed |\n| 4xx  | **Client Error** - The request contains invalid syntax or cannot be fulfilled  |\n| 400  | Bad request - Invalid parameters or malformed JSON                             |\n| 401  | Unauthorized - API key missing or invalid                                      |\n| 403  | Forbidden - Authenticated but not allowed                                      |\n| 404  | Not found - Resource does not exist                                            |\n| 422  | Unprocessable Entity - Well-formed request but cannot be processed             |\n| 500  | Internal server error - Unexpected error on our side.                          |\n\n### Error Response Format\n\nWhen an error occurs, the response includes a status message and a body in JSON format with an `error` field with\nadditional information. For example:\n\n```bash\n    HTTP/1.1 403 Forbidden\n    {\n      \"error\": \"Auth failed. No such API Key\",\n    }\n```\n\n## Authentication\n\nAll endpoints require a jwt token supplied as a Bearer token in the `Authorization` header or an API key provided as the value of the `X-API-KEY` header. For example:\n\n```bash\ncurl -H 'Authorization: Bearer my_authentication_token'\n```\n\n```bash\ncurl -H 'Authorization: X-API-KEY my_api_key'\n```\n\n### Managing API Keys\n\nCreate and manage keys in\nthe [Fluence Console › Settings › API Keys](https://console.fluence.network/settings/api-keys).\n\n- **Read-only keys** – retrieve information only\n- **Full-access keys** – manage all resources\n\n> **Important**: API keys are only displayed once during creation for security reasons. Store them safely - if a key is\n> lost, expired or compromised, you'll need to delete it and create a new one.\n\n### Key Security\n\nAPI keys function as complete authentication credentials, similar to a username/password combination. Therefore:\n\n- Keep your keys secure and never share them\n- Use HTTPS for all API requests\n- Rotate keys periodically\n- Set appropriate expiration dates when creating keys\n- Delete compromised keys immediately\n\n## Cloud-init\n\nOptional `cloudInit.userData` on `POST /v2/vms` lets you bootstrap the VM with a\n[cloud-init](https://cloudinit.readthedocs.io/) configuration. The payload is\nforwarded to the VM backend verbatim; vodopad does not parse or validate the\ncontent beyond a 16 KiB byte cap.\n\n```bash\ncurl -X POST https://api.fluence.dev/v2/vms \\\n  -H \"Authorization: X-API-KEY <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n        \"clusterId\": \"...\",\n        \"name\": \"demo\",\n        \"configurationId\": \"...\",\n        \"bootDisk\": { \"...\": \"...\" },\n        \"sshKeys\": [\"...\"],\n        \"cloudInit\": {\n          \"userData\": \"#cloud-config\\nruncmd:\\n  - echo hello\\n\"\n        }\n      }'\n```\n\nNotes:\n\n- **Create-only.** `userData` is meaningful only on `POST /v2/vms`. `PATCH` requests have no `userData` field; sending one is dropped during JSON deserialization.\n- **Ephemeral.** The content is stored only until the VM transitions to `Launched` (or `Failed` on create-deadline, or `Terminating`/`Terminated` on termination), then erased in the same transaction as the status change. After that, listing or fetching the VM returns a non-null `cloudInit` object (no fields) as a permanent marker but never the original content.\n- **Length limit.** Maximum 16 KiB enforced as a **byte count** (UTF-8 multi-byte characters are counted by their byte size, not code-point count). Oversize requests are rejected with `400 Bad Request`.\n- **Privacy.** The content is never echoed back through any API endpoint. With request-body debug logging enabled (`RUST_LOG=vodopad::api::server=debug` or `sqlx=debug`), `userData` will appear in logs — see Operator notes below.\n- **Backend rejection.** Malformed userData (e.g. invalid YAML) is detected by the VM backend during provisioning and surfaces as a `Failed` VM status, not a synchronous `400`.\n\n### Operator notes\n\n- The side-table `crd.user_virtual_machine_cloud_init` keeps a row per VM that ever had cloud-init. After successful handoff to the VM backend (status `Launching` or `Launched`) — or upon terminal cleanup (`Failed` from create-deadline timeout, or `Terminating`/`Terminated` from termination) — the row's `user_data` column is set to `NULL` in the same transaction as the status change. The row itself stays as a permanent \"had cloud-init\" marker — its existence is the source of truth for the non-null `cloudInit` object on the response.\n- WAL/audit logs and `pg_dump` backups can preserve the **pre-wipe** state (raw `user_data` bytes) until they roll over. Treat these artefacts as carrying potentially-sensitive material; restrict access and retention accordingly.\n- Do not enable `RUST_LOG=vodopad::api::server=debug` in production — the request/response body logger (`buffer_and_print` in `api/server.rs`) writes every UTF-8 body verbatim to `tracing::debug!` with no path-based redaction, and runs *before* validation, so even rejected oversize `userData` payloads end up in the log.\n- Do not set `RUST_LOG=sqlx=debug` in production — sqlx debug logs can include bind values, which would expose `userData` for in-flight queries.\n"
  contact:
    name: Cloudless Labs
  license:
    name: AGPL-3
    identifier: AGPL-3
  version: 0.10.0
security:
- api_key: []
tags:
- name: SecurityGroup
  description: Endpoints to create, view, update and delete security groups
paths:
  /v1/security_groups:
    get:
      tags:
      - SecurityGroup
      operationId: get_user_security_groups
      parameters:
      - name: ids
        in: query
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/UserSecurityGroupId'
      - name: clusterId
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ClusterId'
      - name: vpcId
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/UserVpcId'
      - name: name
        in: query
        required: false
        schema:
          type: string
      - name: status
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/UserSecurityGroupStatusDto'
      - name: page
        in: query
        required: false
        schema:
          type: integer
          format: u-int64
          minimum: 0
      - name: perPage
        in: query
        required: false
        schema:
          type: integer
          format: u-int64
          minimum: 0
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_UserSecurityGroupDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: bad_request
                error: Wrong parameters
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: unauthorized
                error: Auth token invalid or missing
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: forbidden
                error: Not allowed to call this endpoint
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: unprocessable_entity
                error: Unable to process the entity
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: internal_server_error
                error: Unexpected server error
      security:
      - access_jwt_token:
        - security_group:read
      - api_key:
        - security_group:read
    post:
      tags:
      - SecurityGroup
      operationId: create_user_security_group
      requestBody:
        description: Create a new user security group
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserSecurityGroupRequest'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSecurityGroupDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: bad_request
                error: Wrong parameters
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: unauthorized
                error: Auth token invalid or missing
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: forbidden
                error: Not allowed to call this endpoint
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: unprocessable_entity
                error: Unable to process the entity
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: internal_server_error
                error: Unexpected server error
      security:
      - access_jwt_token:
        - security_group:write
      - api_key:
        - security_group:write
  /v1/security_groups/delete:
    post:
      tags:
      - SecurityGroup
      operationId: delete_user_security_groups
      requestBody:
        description: Security group IDs to remove
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserSecurityGroupIdsDto'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserSecurityGroupDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: bad_request
                error: Wrong parameters
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: unauthorized
                error: Auth token invalid or missing
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: forbidden
                error: Not allowed to call this endpoint
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: unprocessable_entity
                error: Unable to process the entity
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: internal_server_error
                error: Unexpected server error
      security:
      - access_jwt_token:
        - security_group:write
      - api_key:
        - security_group:write
  /v1/security_groups/{security_group_id}:
    delete:
      tags:
      - SecurityGroup
      operationId: delete_user_security_group
      parameters:
      - name: security_group_id
        in: path
        description: The ID of the security group to remove
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSecurityGroupDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: bad_request
                error: Wrong parameters
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: unauthorized
                error: Auth token invalid or missing
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: forbidden
                error: Not allowed to call this endpoint
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: unprocessable_entity
                error: Unable to process the entity
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: internal_server_error
                error: Unexpected server error
      security:
      - access_jwt_token:
        - security_group:write
      - api_key:
        - security_group:write
    patch:
      tags:
      - SecurityGroup
      operationId: update_user_security_group
      parameters:
      - name: security_group_id
        in: path
        description: The ID of the security group to update
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: Update an existing user security group
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserSecurityGroupRequest'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSecurityGroupDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: bad_request
                error: Wrong parameters
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: unauthorized
                error: Auth token invalid or missing
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: forbidden
                error: Not allowed to call this endpoint
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: unprocessable_entity
                error: Unable to process the entity
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                code: internal_server_error
                error: Unexpected server error
      security:
      - access_jwt_token:
        - security_group:write
      - api_key:
        - security_group:write
components:
  schemas:
    ErrorCode:
      type: string
      description: 'Stable, machine-readable error code carried by every non-2xx response.


        Clients should branch on `code` rather than parsing the human-readable

        `error` string. Status-derived variants cover any error that does not

        supply a more specific code; semantic variants are set explicitly at the

        construction site (see `VodopadError::code`).'
      enum:
      - bad_request
      - unauthorized
      - forbidden
      - not_found
      - conflict
      - unprocessable_entity
      - not_acceptable
      - insufficient_balance
      - service_unavailable
      - internal_server_error
    SecurityGroupRuleDto:
      oneOf:
      - allOf:
        - $ref: '#/components/schemas/SecurityGroupRuleKindDto'
        - type: object
          required:
          - type
          properties:
            type:
              type: string
              enum:
              - ipv4
      - allOf:
        - $ref: '#/components/schemas/SecurityGroupRuleKindDto'
        - type: object
          required:
          - type
          properties:
            type:
              type: string
              enum:
              - ipv6
    PaginatedResponse_UserSecurityGroupDto:
      type: object
      required:
      - items
      - pagination
      properties:
        items:
          type: array
          items:
            type: object
            required:
            - id
            - userId
            - clusterId
            - vpcId
            - name
            - status
            - ingressRules
            - egressRules
            - createdAt
            - attachedTo
            properties:
              attachedTo:
                type: array
                items:
                  $ref: '#/components/schemas/UserVmNetworkInterfaceId'
              clusterId:
                $ref: '#/components/schemas/ClusterId'
              createdAt:
                type: string
                format: date-time
              egressRules:
                $ref: '#/components/schemas/SecurityGroupRulesDto'
              id:
                $ref: '#/components/schemas/UserSecurityGroupId'
              ingressRules:
                $ref: '#/components/schemas/SecurityGroupRulesDto'
              name:
                type: string
              readySince:
                type:
                - string
                - 'null'
                format: date-time
              removedAt:
                type:
                - string
                - 'null'
                format: date-time
              status:
                $ref: '#/components/schemas/UserSecurityGroupStatusDto'
              userId:
                $ref: '#/components/schemas/UserId'
              vpcId:
                $ref: '#/components/schemas/UserVpcId'
        pagination:
          $ref: '#/components/schemas/PaginationInfo'
    UserSecurityGroupIdsDto:
      type: object
      required:
      - ids
      properties:
        ids:
          type: array
          items:
            $ref: '#/components/schemas/UserSecurityGroupId'
    UpdateUserSecurityGroupRequest:
      type: object
      properties:
        egressRules:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/SecurityGroupRulesDto'
        ingressRules:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/SecurityGroupRulesDto'
            description: '`absent` — не менять; `null` — сбросить к дефолту (`AllowAll`);

              объект — установить конкретные правила.'
        name:
          type:
          - string
          - 'null'
    SgProtocolKindDto:
      oneOf:
      - type: string
        enum:
        - all
      - type: string
        enum:
        - icmp
      - type: object
        required:
        - tcp
        properties:
          tcp:
            type: object
            required:
            - ports
            properties:
              ports:
                $ref: '#/components/schemas/PortsDto'
      - type: object
        required:
        - udp
        properties:
          udp:
            type: object
            required:
            - ports
            properties:
              ports:
                $ref: '#/components/schemas/PortsDto'
    ErrorBody:
      type: object
      required:
      - error
      - code
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
          description: The stable, machine-readable error code.
        error:
          type: string
          description: The human-readable error message.
    SgRemoteDto:
      oneOf:
      - type: object
        required:
        - address
        properties:
          address:
            type: string
        example: 127.0.0.1/32
      - type: object
        required:
        - securityGroup
        properties:
          securityGroup:
            $ref: '#/components/schemas/UserSecurityGroupId'
    UserSecurityGroupId:
      type: string
      format: uuid
    ClusterId:
      type: string
      format: uuid
    UserSecurityGroupStatusDto:
      type: string
      enum:
      - new
      - created
      - ready
      - updating
      - failed
      - removing
      - removed
    PortsDto:
      oneOf:
      - type: string
        enum:
        - all
      - type: object
        required:
        - exact
        properties:
          exact:
            type: object
            required:
            - value
            properties:
              value:
                type: integer
                format: u-int16
                minimum: 0
      - type: object
        required:
        - range
        properties:
          range:
            type: object
            required:
            - min
            - max
            properties:
              max:
                type: integer
                format: u-int16
                minimum: 0
              min:
                type: integer
                format: u-int16
                minimum: 0
    UserId:
      type: string
      format: uuid
    PaginationInfo:
      type: object
      required:
      - totalRecords
      - filteredRecords
      - totalPages
      - currentPage
      - perPage
      properties:
        currentPage:
          type: integer
          format: u-int64
          minimum: 0
        filteredRecords:
          type: integer
          format: u-int64
          minimum: 0
        perPage:
          type: integer
          format: u-int64
          minimum: 0
        totalPages:
          type: integer
          format: u-int32
          minimum: 0
        totalRecords:
          type: integer
          format: u-int64
          minimum: 0
    SecurityGroupRuleKindDto:
      type: object
      required:
      - protocolKind
      - remote
      properties:
        protocolKind:
          $ref: '#/components/schemas/SgProtocolKindDto'
        remote:
          $ref: '#/components/schemas/SgRemoteDto'
    CreateUserSecurityGroupRequest:
      type: object
      required:
      - clusterId
      - name
      properties:
        clusterId:
          $ref: '#/components/schemas/ClusterId'
        egressRules:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/SecurityGroupRuleDto'
        ingressRules:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/SecurityGroupRuleDto'
        name:
          type: string
    UserSecurityGroupDto:
      type: object
      required:
      - id
      - userId
      - clusterId
      - vpcId
      - name
      - status
      - ingressRules
      - egressRules
      - createdAt
      - attachedTo
      properties:
        attachedTo:
          type: array
          items:
            $ref: '#/components/schemas/UserVmNetworkInterfaceId'
        clusterId:
          $ref: '#/components/schemas/ClusterId'
        createdAt:
          type: string
          format: date-time
        egressRules:
          $ref: '#/components/schemas/SecurityGroupRulesDto'
        id:
          $ref: '#/components/schemas/UserSecurityGroupId'
        ingressRules:
          $ref: '#/components/schemas/SecurityGroupRulesDto'
        name:
          type: string
        readySince:
          type:
          - string
          - 'null'
          format: date-time
        removedAt:
          type:
          - string
          - 'null'
          format: date-time
        status:
          $ref: '#/components/schemas/UserSecurityGroupStatusDto'
        userId:
          $ref: '#/components/schemas/UserId'
        vpcId:
          $ref: '#/components/schemas/UserVpcId'
    UserVpcId:
      type: string
      format: uuid
    SecurityGroupRulesDto:
      oneOf:
      - type: object
        required:
        - type
        properties:
          type:
            type: string
            enum:
            - allowAll
      - type: object
        required:
        - rules
        - type
        properties:
          rules:
            type: array
            items:
              $ref: '#/components/schemas/SecurityGroupRuleDto'
          type:
            type: string
            enum:
            - allow
    UserVmNetworkInterfaceId:
      type: string
      format: uuid
  securitySchemes:
    access_jwt_token:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token issued by Fluence
    api_key:
      type: apiKey
      in: header
      name: X-API-KEY