DPF Connections API

openapi: 3.2.0
info:
  title: DPF Connections API
  version: 1.1.0
  description: '## Common error responses


    Unless otherwise noted, any authenticated endpoint may also return the following

    responses, each with the standard `ErrorResponse` body. To avoid repetition they are

    not listed individually on each operation:


    - **400 Bad Request** — malformed JSON, unknown action, or missing/invalid fields

    - **401 Unauthorized** — missing or invalid JWT bearer token

    - **402 Payment Required** — the account has insufficient credits or an inactive subscription

    - **403 Forbidden** — authenticated but not permitted (no access to the resource, or a higher access level / plan tier is required)


    Operation-specific responses (e.g. `404`, `409`) are documented on each endpoint.'
  contact:
    name: Contact DPF
    url: mailto:contact@dpf-it.com
  license:
    name: Proprietary
    url: https://dpf-it.com/#terms
servers:
- url: https://api.dpf-it.com
  description: Production API
security: []
tags:
- name: Connections
  description: Workspace external connections (e.g. SFTP) with managed keypairs
paths:
  /connections:
    post:
      tags:
      - Connections
      summary: Manage workspace external connections (SFTP, AWS S3)
      description: 'Multi-action endpoint for workspace connections. The `action` field determines the operation.

        Supported connection `type`s are `sftp` and `aws_s3`.


        For SFTP, DPF generates an RSA-4096 keypair when the connection is created. The **public key**

        is returned so it can be installed in the remote server''s `authorized_keys`; the **private key**

        is retained server-side and is **never** returned by any action.


        For `aws_s3`, DPF generates an **ExternalId** when the connection is created and returns a ready-to-paste

        **trust policy** (naming DPF''s dedicated connector role as principal, gated by that ExternalId) along with

        `dpfPrincipalArn`. The customer creates (or updates) an IAM role in their own AWS account with that trust

        policy and a permissions policy of their choosing, granting exactly the S3 access DPF needs. No credential

        is ever stored — DPF assumes the customer''s role on demand via `sts:AssumeRole`.


        Every connection tracks `lastTestStatus`/`lastTestedAt` from its most recent `test-connection` call. A

        connection must have `lastTestStatus: passed` before it can be used to create or run a trigger (see

        `/job-triggers`) — this also self-heals: if a scheduled run''s connect/assume-role step fails, the

        connection is flipped back to `failed`, blocking further use until it''s re-tested.


        **Actions:**


        - **create-connection**: Create a connection. For `sftp`, generates the keypair and returns the public

        key. For `aws_s3`, generates the ExternalId and returns the trust policy.

        - Returns: `Connection` (with `publicKey` for sftp, or `externalId`/`dpfPrincipalArn`/`trustPolicy` for

        aws_s3 — never `privateKey`) with status 201

        - Requires: JWT token, full access to the workspace

        - Fields (sftp): `workspaceId`, `type: sftp`, `hostname`, optional `username` (defaults to `sftpuser`)

        - Fields (aws_s3): `workspaceId`, `type: aws_s3`, `roleArn` (the IAM role the customer will create/update)


        - **get-connections**: List all connections for a workspace.

        - Returns: `GetConnectionsResponse` with status 200 (each item includes `publicKey`, never `privateKey`)

        - Requires: JWT token, any access (full or read-only) to the workspace


        - **test-connection**: Verify a connection works. For SFTP, connects with the stored private key

        and lists the home directory. For `aws_s3`, assumes the customer''s role (via DPF''s connector role

        and the stored ExternalId) and calls `GetCallerIdentity`. Success means authentication worked (an

        empty SFTP directory listing still counts as success). Also updates `lastTestStatus`/`lastTestedAt`.

        - Returns: `TestConnectionResponse` with status 200. A reachable-but-failed test returns

        `success: false` with a reason (not an HTTP error).

        - Requires: JWT token, any access (full or read-only) to the workspace


        - **delete-connection**: Delete a connection (and its stored keypair, for sftp). Idempotent.

        - Returns: `DeleteConnectionResponse` with status 200

        - Requires: JWT token, full access to the workspace'
      operationId: manageConnections
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/CreateConnectionRequest'
              - $ref: '#/components/schemas/GetConnectionsRequest'
              - $ref: '#/components/schemas/TestConnectionRequest'
              - $ref: '#/components/schemas/DeleteConnectionRequest'
            examples:
              createConnection:
                summary: Create an SFTP connection
                value:
                  action: create-connection
                  workspaceId: 550e8400-e29b-41d4-a716-446655440000
                  type: sftp
                  hostname: sftp.example.com
                  username: sftpuser
              createAwsS3Connection:
                summary: Create an aws_s3 connection
                value:
                  action: create-connection
                  workspaceId: 550e8400-e29b-41d4-a716-446655440000
                  type: aws_s3
                  roleArn: arn:aws:iam::123456789012:role/dpf-ingestion
              getConnections:
                summary: List connections
                value:
                  action: get-connections
                  workspaceId: 550e8400-e29b-41d4-a716-446655440000
              testConnection:
                summary: Test a connection
                value:
                  action: test-connection
                  workspaceId: 550e8400-e29b-41d4-a716-446655440000
                  connectionId: 7b3f8a10-1c2d-4e5f-9a0b-1c2d3e4f5a6b
              deleteConnection:
                summary: Delete a connection
                value:
                  action: delete-connection
                  workspaceId: 550e8400-e29b-41d4-a716-446655440000
                  connectionId: 7b3f8a10-1c2d-4e5f-9a0b-1c2d3e4f5a6b
      responses:
        '201':
          description: Connection created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateConnectionResponse'
        '200':
          description: Connections listed, connection tested, or connection deleted
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/GetConnectionsResponse'
                - $ref: '#/components/schemas/TestConnectionResponse'
                - $ref: '#/components/schemas/DeleteConnectionResponse'
        '403':
          description: No access, or read-only access attempting a mutating action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Connection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Machine-readable error code
              example: INVALID_EMAIL
            message:
              type: string
              description: Human-readable error message
              example: Invalid email format
    DeleteConnectionResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            connectionId:
              type: string
              format: uuid
            message:
              type: string
              example: Connection deleted successfully
    TestConnectionResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            connectionId:
              type: string
              format: uuid
            success:
              type: boolean
              description: Whether the connection test itself succeeded.
              example: true
            entryCount:
              type: integer
              description: sftp only. Number of directory entries returned (present on success).
              example: 3
            fileCount:
              type: integer
              description: sftp only. Number of regular files in the listing (present on success).
              example: 2
            account:
              type: string
              description: aws_s3 only. The AWS account ID of the assumed role (present on success).
              example: '123456789012'
            assumedRoleArn:
              type: string
              description: aws_s3 only. The full STS-assumed-role identity ARN (present on success).
              example: arn:aws:sts::123456789012:assumed-role/dpf-ingestion/dpf-test
            message:
              type: string
              example: Connected successfully. Listed 3 entries (2 files).
    CreateConnectionRequest:
      type: object
      description: '`hostname` (and optional `username`) are required when `type: sftp`; `roleArn` is required when

        `type: aws_s3`.

        '
      required:
      - action
      - workspaceId
      - type
      properties:
        action:
          type: string
          enum:
          - create-connection
        workspaceId:
          type: string
          format: uuid
        type:
          type: string
          enum:
          - sftp
          - aws_s3
        hostname:
          type: string
          description: sftp only, required for that type.
          example: sftp.example.com
        username:
          type: string
          description: sftp only. Optional, defaults to "sftpuser".
          example: sftpuser
        roleArn:
          type: string
          description: aws_s3 only, required for that type. The IAM role the customer will create/update.
          example: arn:aws:iam::123456789012:role/dpf-ingestion
    TestConnectionRequest:
      type: object
      required:
      - action
      - workspaceId
      - connectionId
      properties:
        action:
          type: string
          enum:
          - test-connection
        workspaceId:
          type: string
          format: uuid
        connectionId:
          type: string
          format: uuid
    Connection:
      type: object
      description: A workspace connection. The private key is never included.
      properties:
        connectionId:
          type: string
          format: uuid
          example: 7b3f8a10-1c2d-4e5f-9a0b-1c2d3e4f5a6b
        workspaceId:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        type:
          type: string
          enum:
          - sftp
          - aws_s3
          example: sftp
        hostname:
          type: string
          description: sftp only.
          example: sftp.example.com
        username:
          type: string
          description: sftp only.
          example: sftpuser
        publicKey:
          type: string
          description: sftp only. OpenSSH public key to install in the remote server's authorized_keys.
          example: ssh-rsa AAAAB3NzaC1yc2EAAA... dpf-446655440000
        roleArn:
          type: string
          description: aws_s3 only. The customer's IAM role ARN.
          example: arn:aws:iam::123456789012:role/dpf-ingestion
        externalId:
          type: string
          description: aws_s3 only. DPF-generated; required in the customer's trust policy.
          example: 3f9c2e1a-5b6d-4c7e-8f9a-0b1c2d3e4f5a
        dpfPrincipalArn:
          type: string
          description: aws_s3 only. The DPF connector role ARN the customer's trust policy must name as principal.
          example: arn:aws:iam::442707444240:role/dpf-aws-connector
        createdBy:
          type: string
          format: uuid
        createdAt:
          type: integer
          format: int64
          description: Unix timestamp in milliseconds
        updatedAt:
          type: integer
          format: int64
          description: Unix timestamp in milliseconds
        lastTestStatus:
          type: string
          enum:
          - passed
          - failed
          description: Outcome of the most recent test-connection call, if any test has been run.
        lastTestedAt:
          type: integer
          format: int64
          description: Unix timestamp in milliseconds of the most recent test-connection call, if any.
    GetConnectionsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            connections:
              type: array
              items:
                $ref: '#/components/schemas/Connection'
            count:
              type: integer
              example: 1
    CreateConnectionResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          allOf:
          - $ref: '#/components/schemas/Connection'
          - type: object
            properties:
              message:
                type: string
              trustPolicy:
                type: object
                description: aws_s3 only. Ready-to-paste IAM trust policy naming dpfPrincipalArn as principal, gated by externalId.
                example:
                  Version: '2012-10-17'
                  Statement:
                  - Effect: Allow
                    Principal:
                      AWS: arn:aws:iam::442707444240:role/dpf-aws-connector
                    Action: sts:AssumeRole
                    Condition:
                      StringEquals:
                        sts:ExternalId: 3f9c2e1a-5b6d-4c7e-8f9a-0b1c2d3e4f5a
    DeleteConnectionRequest:
      type: object
      required:
      - action
      - workspaceId
      - connectionId
      properties:
        action:
          type: string
          enum:
          - delete-connection
        workspaceId:
          type: string
          format: uuid
        connectionId:
          type: string
          format: uuid
    GetConnectionsRequest:
      type: object
      required:
      - action
      - workspaceId
      properties:
        action:
          type: string
          enum:
          - get-connections
        workspaceId:
          type: string
          format: uuid
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from login or registration