SFTP Connections API

This API provides comprehensive functionality for managing SFTP connections and performing file operations on remote SFTP servers. It is part of the Borrower Central system and requires proper authentication and authorization.

Base URL

All endpoints are prefixed with /store-sftp-connections

Authentication & Authorization

All endpoints require authentication via the validate_request_v2 mechanism and specific permissions:

secrets.read: Required for read operations (listing, downloading, viewing connection details)
secrets.write: Required for write operations (creating connections, uploading, deleting, moving files)
secrets.delete: Required for deleting connections

The SFTPConnection Object

The SFTPConnection object represents an SFTP connection configuration in the system.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "host": "sftp.example.com",
  "label": "My SFTP Server",
  "tenant": "tenant-id",
  "createdAt": "2024-01-01T12:00:00Z",
  "updatedAt": "2024-01-01T15:30:00Z"
}

Attributes

Attribute	Description	Type
id	Unique identifier of the connection	String
host	SFTP server hostname or IP address	String
label	Human-friendly name for the connection	String
tenant	Tenant identifier	String
createdAt	Date and time when connection was created	String (ISO 8601)
updatedAt	Date and time of last update	String (ISO 8601)

Available Operations

Create a new SFTP Connection

Creates a new SFTP connection configuration.

POST /store-sftp-connections

Input Parameters

Parameter	Description	Type	Required
label	Human-friendly name for the connection	String	Yes
host	SFTP server hostname or IP address	String	Yes
port	Port number (default: 22, range: 1-65535)	Integer	No
username	SFTP username	String	Yes
password	SFTP password	String	Yes

Request Example

{
  "label": "My SFTP Server",
  "host": "sftp.example.com",
  "port": 22,
  "username": "user123",
  "password": "secure_password"
}

Successful Response

{
  "id": "connection-uuid"
}

Get an SFTP Connection

Retrieves details of a specific SFTP connection.

GET /store-sftp-connections/:connection_id

Path Parameters

Parameter	Description
:connection_id	Unique identifier of the SFTP connection

Successful Response

Returns the complete SFTPConnection object.

List SFTP Connections

Retrieves a paginated list of SFTP connections with search and sorting capabilities.

GET /store-sftp-connections

Query Parameters

Parameter	Description	Type
search	Text query to search connections	String
page	Page number (default: 1)	Integer
per-page	Items per page (default: 10)	Integer
sort-by	Field to sort by	String
sort-direction	Sort direction (asc or desc)	String

Successful Response

Paginated list of SFTPConnection objects.

Test an SFTP Connection

Tests the connectivity and authentication of an SFTP connection.

POST /store-sftp-connections/:connection_id/test

Path Parameters

Parameter	Description
:connection_id	Unique identifier of the SFTP connection

Successful Response

{
    "success": true,
    "message": "Connection test completed",
    "details": {
        "connection": {
            "success": true,
            "message": "Connection established"
        },
        "basePath": {
            "success": true,
            "message": "Base path '/' is accessible",
            "path": "/"
        }
    }
}

Delete an SFTP Connection

Permanently deletes an SFTP connection configuration.

DELETE /store-sftp-connections/:connection_id

Path Parameters

Parameter	Description
:connection_id	Unique identifier of the SFTP connection

Successful Response

Status code 204 (No Content) if deletion was successful.

File Operations

List Directory Contents

Lists files and directories at the specified path on the SFTP server.

GET /store-sftp-connections/:connection_id/list

Path Parameters

Parameter	Description
:connection_id	Unique identifier of the SFTP connection

Query Parameters

Parameter	Description	Type	Required
path	Remote path to list (e.g., `/home/user/docs`)	String	Yes

Successful Response

[
  {
    "name": "file1.txt",
    "path": "/home/user/documents/file1.txt",
    "createdAt": "2023-08-08T23:57:28+00:00",
    "size": 0,
    "isDirectory": false
  },
  {
    "name": "subfolder",
    "path": "/home/user/documents/subfolder",
    "createdAt": "2023-08-08T23:57:28+00:00",
    "size": 0,
    "isDirectory": true
  }
]

Download File

Downloads a file from the SFTP server and creates a store package.

POST /store-sftp-connections/:connection_id/download

Path Parameters

Parameter	Description
:connection_id	Unique identifier of the SFTP connection

Input Parameters

Parameter	Description	Type	Required
path	Path to the remote file	String	Yes

Request Example

{
  "path": "/path/to/remote/file.txt"
}

Successful Response

{
  "packageId": "package-uuid"
}

Download File (Direct URL)

Downloads a file from the SFTP server and returns a direct download URL.

POST /store-sftp-connections/:connection_id/download-url

Path Parameters

Parameter	Description
:connection_id	Unique identifier of the SFTP connection

Input Parameters

Parameter	Description	Type	Required
path	Path to the remote file	String	Yes

Request Example

{
  "path": "/path/to/remote/file.txt"
}

Successful Response

{
  "downloadUrl": "https://example.com/download/temporary-url",
  "filename": "file.txt"
}

Upload File

POST /store-sftp-connections/{connection_id}/upload

Uploads a file from an attachment to the SFTP server.

Request Body:

{
  "attachmentId": "attachment-uuid",
  "remotePath": "/path/to/remote/directory",
  "filename": "custom-filename.txt"
}

Fields:

attachmentId (string, required): ID of the attachment to upload
remotePath (string, optional): Remote directory path (defaults to root)
filename (string, optional): Custom filename (uses original if not provided)

Response: 201 Created

{
  "path": "/path/to/remote/directory/custom-filename.txt",
  "size": 2048
}

Get File/Directory Information

POST /store-sftp-connections/{connection_id}/stat

Retrieves detailed information about a file or directory.

Request Body:

{
  "path": "/path/to/file/or/directory"
}

Response: 200 OK

{
    "path": "/data",
    "name": "data",
    "size": 0,
    "permissions": "0o40775",
    "uid": 0,
    "gid": 1011,
    "isDirectory": true,
    "isFile": false,
    "isSymlink": false,
    "modifiedAt": "2023-01-10T13:49:28+00:00",
    "accessedAt": "2023-01-10T15:11:47+00:00"
}

Create Directory

POST /store-sftp-connections/{connection_id}/mkdir

Creates a new directory on the SFTP server.

Request Body:

{
  "path": "/path/to/new/directory",
  "mode": 755
}

Fields:

path (string, required): Path of the directory to create
mode (integer, optional): Directory permissions in octal format (default: 755)

Response: 201 Created

{
    "path": "/data/hellodir",
    "mode": "0o755",
    "operation": "mkdir",
    "success": true,
    "message": "Successfully created directory: /data/hellodir"
}

Delete File/Directory

POST /store-sftp-connections/{connection_id}/delete-file

Deletes a single file or directory from the SFTP server.

Request Body:

{
  "path": "/data/hellodir"
}

Response: 200 OK

{
    "path": "/data/hellodir",
    "operation": "rmdir",
    "success": true,
    "message": "Successfully deleted directory: /data/hellodir"
}

Bulk Delete Files

POST /store-sftp-connections/{connection_id}/bulk-delete

Deletes multiple files or directories from the SFTP server.

Request Body:

{
  "paths": [
    "/path/to/file1.txt",
    "/path/to/file2.txt",
    "/path/to/directory"
  ]
}

Fields:

paths (array, required): List of paths to delete (1-50 items)

Response: 200 OK

{
    "operation": "bulk_delete",
    "totalPaths": 1,
    "successfulCount": 1,
    "failedCount": 1,
    "successful": [
        {
            "path": "/data/test2",
            "operation": "rmdir",
            "success": true,
            "message": "Successfully deleted: /data/test2"
        }
    ],
    "failed": [
        {
            "path": "/data/test",
            "operation": "rmdir",
            "success": false,
            "message": "Successfully deleted: /data/test"
        }
    ],
    "success": true,
    "message": "Deleted 1 of 2 items"
}

Move/Rename File

POST /store-sftp-connections/{connection_id}/move

Moves or renames a file or directory on the SFTP server.

Request Body:

{
  "sourcePath": "/path/to/source/file.txt",
  "destinationPath": "/path/to/destination/file.txt"
}

Response: 200 OK

{
  "sourcePath": "/path/to/source/file.txt",
  "destinationPath": "/path/to/destination/file.txt",
  "success": true,
  "message": "File moved successfully"
}

Copy File

POST /store-sftp-connections/{connection_id}/copy

Copies a file or directory on the SFTP server.

Request Body:

{
  "sourcePath": "/path/to/source/file.txt",
  "destinationPath": "/path/to/destination/file.txt"
}

Response: 200 OK

{
  "sourcePath": "/path/to/source/file.txt",
  "destinationPath": "/path/to/destination/file.txt",
  "success": true,
  "message": "File copied successfully"
}

Error Handling

The API can return the following error codes:

Code	Description
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

Errors include a descriptive message in the response body.

Rate Limits

Bulk delete operations are limited to 50 paths per request
File operations may have size limits depending on server configuration
Connection testing should be used sparingly to avoid server overload

Security Considerations

All credentials are encrypted at rest
SFTP connections use secure authentication mechanisms
File operations are restricted to the authenticated user's accessible directories
All operations are logged for audit purposes
Temporary download URLs have expiration times for security

Examples

Complete Workflow Example

# 1. Create an SFTP connection
curl -X POST /store-sftp-connections \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Production Server",
    "host": "prod.example.com",
    "username": "deploy",
    "password": "secure123"
  }'
 
# 2. Test the connection
curl -X POST /store-sftp-connections/{connection_id}/test
 
# 3. List files in a directory
curl -X GET "/store-sftp-connections/{connection_id}/list?path=/uploads"
 
# 4. Upload a file
curl -X POST /store-sftp-connections/{connection_id}/upload \
  -H "Content-Type: application/json" \
  -d '{
    "attachmentId": "file-attachment-id",
    "remotePath": "/uploads",
    "filename": "report.pdf"
  }'
 
# 5. Download the file
curl -X POST /store-sftp-connections/{connection_id}/download \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/uploads/report.pdf"
  }'

On this page