# sFTP

### Overview

This article describes how to configure your SFTP server to allow Birdie to export data to a dedicated path.

Birdie can deliver processed data (e.g., enriched feedback, areas, opportunities) to your SFTP server. We recommend creating:

* A dedicated **user and directory** for Birdie exports
* SSH **key-based authentication** (passwords are not recommended)

This isolates write access from your existing data and avoids credential rotation overhead.

#### Step 1: Create a dedicated user and directory for exports

Create a dedicated user and a directory where Birdie will write export files:

```
/home/birdie/exports/
```

The user must have **write access** to this directory and any subdirectories Birdie creates inside it.

#### Step 2: Generate an SSH key pair

Generate an RSA key pair that Birdie will use to authenticate. The recommended length is at least 2048 bits.

```bash
ssh-keygen -t rsa -b 4096 -f birdie_export -N ""
```

This produces two files:

* `birdie_export` — the **private key**, which you will share with Birdie.
* `birdie_export.pub` — the **public key**, which you will install on your server.

Append the public key to the dedicated user's `~/.ssh/authorized_keys` file and ensure permissions are correct:

```bash
mkdir -p /home/birdie/.ssh
cat birdie_export.pub >> /home/birdie/.ssh/authorized_keys
chmod 700 /home/birdie/.ssh
chmod 600 /home/birdie/.ssh/authorized_keys
chown -R birdie:birdie /home/birdie/.ssh
```

#### Step 3: Confirm the server's public key fingerprint

Birdie validates the server's host key on every connection to prevent man-in-the-middle attacks. Capture the server's public key:

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

Save this value to share with Birdie in the next step.

#### Step 4: Share export configuration with Birdie

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

```json
{
  "connection_details": {
    "address": "sftp.example.com",
    "port": "22",
    "username": "birdie",
    "server_public_key": "ssh-rsa AAAA..."
  },
  "data_source": {
    "path": "exports/"
  }
}
```

| 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 Birdie will write export files (Step 1).                        |

[Share credentials securely](https://ask.birdie.ai/integrations-and-data-ingestion/securely-sharing-credentials-for-data-integration) with the Birdie team. Never send credentials via email or unencrypted channels.

### How the Export Works

Birdie delivers daily exports into date-stamped subfolders inside the configured path:

```
{configured-path}/export/2025-01-01/feedbacks.csv
{configured-path}/export/2025-01-02/feedbacks.csv
...
```

Each folder contains the standard set of export files:

* `feedbacks.csv`
* `areas.csv`
* `opportunities.csv`
* `area_opportunities.csv`
* `collections.csv`
* `sentences.csv`
* `messages.csv`

The complete set of files is documented in the [data forwarding documentation](https://ask.birdie.ai/~/revisions/imP4CTJ80lIhIX6zY2BL/integrations-and-data-ingestion/how-to-export-with...).

Birdie's exported content is incremental for some of the files. This means you can't rely solely on the latest file to have the full picture of the data you have inside Birdie.

We recommend you use a Data Warehouse or SQL Engine of choice to consolidate and deduplicate these entries so you can use them analytically.

You'll be responsible for keeping an up-to-date, deduplicated copy of each of these tables.

### Exported Data Format

The exported data content will match the schemas described in our [data forwarding documentation](https://ask.birdie.ai/~/revisions/imP4CTJ80lIhIX6zY2BL/integrations-and-data-ingestion/how-to-export-with...).

You can also check this documentation to better understand how to query the consolidated copies of the exported data.

If the schema evolves over time, you'll need to update your table definitions to make sure to include the new columns within your table.

You also need to create a Warehouse / Database system and ETL Pipeline where you consolidate and deduplicate the data. More details on how to do this are given in the [data forwarding documentation](https://ask.birdie.ai/~/revisions/imP4CTJ80lIhIX6zY2BL/integrations-and-data-ingestion/how-to-export-with...).

### References

* [OpenSSH server configuration](https://man.openbsd.org/sshd_config)
* [SSH key generation (`ssh-keygen`)](https://man.openbsd.org/ssh-keygen)
* [How to export with (Data Forwarding)...](https://ask.birdie.ai/~/revisions/imP4CTJ80lIhIX6zY2BL/integrations-and-data-ingestion/how-to-export-with...)
* [Securely sharing credentials for Data Integration](https://ask.birdie.ai/integrations-and-data-ingestion/securely-sharing-credentials-for-data-integration)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ask.birdie.ai/integrations-and-data-ingestion/how-to-export-with.../s3-azure-gcs-1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.