sFTP

Overview

With the SFTP connector, Birdie can import data from files placed on your SFTP server. Once a day Birdie connects to the configured server, reads any new files from the agreed directory, and ingests the records into Birdie.

This is a good fit when you can't (or don't want to) expose a database or API directly to Birdie, but already have a process that drops files onto an SFTP server.

Requirements

• An SFTP server that Birdie can reach over the public internet.

• A dedicated user and directory for Birdie's reads.

• Key-pair authentication (recommended) or password authentication.

• Agreement on file format and schema for each record kind that will be sent (see Schema requirements).

Why key-pair authentication is recommended

Birdie owns and rotates the key pair internally. Only the public key leaves Birdie. The client never handles secrets that need rotation, and Birdie can revoke a key without changing anything on the client side beyond removing one line from authorized_keys.

Step 1 — Create a dedicated user and directory

On your SFTP server, create a user that Birdie will use, and a directory where the files Birdie should read will be placed:

/home/birdie/import/

The user only needs read access to this directory. Write access is not required for ingestion.

Step 2 — Install Birdie's public key

Birdie shares the public half of an internal key pair with you over a secure channel. Install it on the dedicated user's ~/.ssh/authorized_keys file:

mkdir -p /home/birdie/.ssh
echo "<birdie-public-key>" >> /home/birdie/.ssh/authorized_keys
chmod 700 /home/birdie/.ssh
chmod 600 /home/birdie/.ssh/authorized_keys
chown -R birdie:birdie /home/birdie/.ssh

The private half stays inside Birdie's infrastructure and is never shared.

If you can't use key-pair authentication for any reason, Birdie also supports password authentication — share the password with Birdie over a secure channel instead of the public-key step.

Step 3 — (Optional) Share your server's host key

To prevent man-in-the-middle attacks, Birdie can validate your server's host key on every connection. Capture the server's public host key and share it with Birdie:

ssh-keyscan -t rsa <your-sftp-host> 2>/dev/null

If a host key is not provided, Birdie will still connect but won't validate the server identity beyond the SSH protocol defaults.

Step 4 — Agree on file format and schema

Birdie's SFTP connector reads structured files (CSV is the most common; Parquet is also supported for some flows). Before the integration is enabled, you and Birdie will agree on:

• Record kind — what type of feedback or entity each file represents (e.g., support_ticket, csat, review).

• File format — typically csv; alternative formats can be discussed.

• Separator (CSV only) — defaults to ,; configurable per integration.

• Schema — the columns each file must contain. Birdie provides the schema reference for each record kind separately, following the same model as the data ingestion schema documentation.

• Path convention — files can live directly under the configured directory, or under subfolders by kind / source. Birdie's team will agree the layout with you during setup.

Step 5 — Share connection details with Birdie

Once the user, directory, and public key are in place, securely provide Birdie with the following information:

{
  "connection_details": {
    "address": "sftp.example.com",
    "port": "22",
    "username": "birdie",
    "server_public_key": "ssh-rsa AAAA..."
  },
  "data_source": {
    "path": "import/",
    "format": "csv",
    "separator": ",",
    "kind": "support_ticket"
  }
}

Section	Field	Required	Description
connection_details	address	Yes	Hostname or IP address of your SFTP server.
connection_details	port	Yes	Port for the SFTP connection. Typically 22.
connection_details	username	Yes	The dedicated user created in Step 1.
connection_details	server_public_key	No	The server's RSA public host key captured in Step 3. Required when host-key validation is enabled.
connection_details	password	No	Only required when using password authentication instead of key-pair.
data_source	path	Yes	Directory on the SFTP server where files will be placed (configured in Step 1).
data_source	format	Yes	File format. Typically csv; parquet is also supported for some flows.
data_source	separator	No	CSV column separator. Defaults to ,.
data_source	kind	Yes	Record kind agreed with Birdie in Step 4 (e.g., support_ticket, csat, review).

Share credentials securely with the Birdie team. Never send credentials via email or unencrypted channels.

How the Import Works

1. Once a day, Birdie's SFTP connector connects to your server using the configured credentials.

2. It lists files in the configured path that fall within the import window (based on file metadata).

3. For each file, Birdie parses records according to the agreed format and schema, and ingests them into Birdie.

4. Files are not deleted or modified on your server — Birdie only reads.

If a file is added after the daily run, it will be picked up on the next run.

References

• Data Schema Definitions for Birdie Ingestion

• Securely sharing credentials for Data Integration

• OpenSSH server configuration

• SSH authorized_keys format