Connect Pigment with an SFTP server

This article explains how to connect an SFTP server to Pigment to load CSV files stored on the server into a Pigment Block.

Overview

This process begins with configuring access to an SFTP server. You grant access to a user account and generate an SSH key pair to authenticate the SFTP user Pigment uses to connect to the server. On the Pigment side, you create a connection by adding the server settings and the user's private SSH key. After setup, the SFTP connector lets you choose between a fixed file or the most recent file. If your server restricts incoming traffic, you also allowlist Pigment's IP addresses.

⚠️ Important

You must have read access to an SFTP server containing the data you want to load into Pigment.

Setting up access

SFTP Step 1 - Creating an SFTP account

Pigment connects to the target server with a user account identified by an SSH key pair. For security reasons, you should:

• Create a dedicated account for Pigment imports, ensuring it only contains data that Pigment should access.

• Give the account read-only access, meaning the data is uploaded to the server by a separate user or system.

ℹ️ Note

The process for creating the account depends on your specific case, including IT policies, the SFTP server implementation, and other factors.

Please consult your provider or administrator for the specific setup details.

SFTP Step 2 - Generating an SSH key pair

For security reasons, create an SSH key pair specifically dedicated to authenticating this user, and don't reuse these keys on other server locations.

You need to provide the SSH private key to Pigment in the following steps during the integration setup to allow the user account to authenticate. The SSH public key must be transferred to the server for authentication on that end.

Pigment supports the following encryption algorithms and key formats:

• RSA (OpenSSL PEM and ssh.com format)

• DSA  (OpenSSL PEM and ssh.com format)

• ECDSA 256/384/521 (OpenSSL PEM format)

• ED25519 (OpenSSH format)

⚠️ Important

• RSA keys in OpenSSH format are not supported

• Keys must have no passphrase

Here is an example of how to create an RSA 4096-bit key pair in OpenSSL PEM format, which Pigment supports:

ssh-keygen -t rsa -b 4096 -m pem

Alternatively, if you need OpenSSH format, use ED25519 encryption and generate the keys with this command:

ssh-keygen -t ed25519 -noencrypt

⚠️ Important

After generating your SSH key pair, copy the public key to your SFTP server and ensure it’s added to the correct user’s ~/.ssh/authorized_keys file.

Skipping this step causes authentication to fail. You can use ssh-copy-id to do this easily. For more information, see Copying the Public Key to the Server.

SFTP Step 3 - Getting the server SSH host key fingerprint

To secure the connection and prevent man-in-the-middle attacks, you need to provide Pigment with the SSH host key fingerprint of the target server during the integration configuration.

This fingerprint can be obtained on the server side, by using the ssh-keygen command.

Example:

ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key

You can also get it on the client side by combining ssh-keyscan and ssh-keygen:

ssh-keyscan -p $port $host | ssh-keygen -lf -

The expected format is SHA256-base64.

Example:

SHA256:AVf87SpGS622J6Iqv6F79U/y7LMTkSE5N37bRzPw2ek

SFTP Step 4 - Allowlisting Pigment IP addresses

If your SFTP server restricts incoming traffic, allowlist the IP addresses for your Workspace region so Pigment can connect. Pigment does not assign a domain name to the IP addresses of outbound NAT gateways in its private infrastructure. You only need the IPs for your own region.

Each region has a live gateway and a recovery gateway. You should allowlist both gateways for your Workspace region, so your SFTP connections keep working if Pigment needs to move its infrastructure to another region.

The following table lists the outbound gateways by region:

The France IPs apply only to Workspaces hosted on Pigment's sovereign region.

Establishing connection in Pigment

You need to establish a connection for each individual SFTP location.

To establish a connection in Pigment:

1. In your Workspace, go to Settings then select Integrations.

2. Select + Add next to the SFTP integration and fill out the form with the following information:

   • Name. Give a name to your connection.

   • Application access. Select the applications that can use this connection.

   • Host name or address. Type the name or IP address of the SFTP server. If the server restricts incoming traffic, see SFTP Step 4 - Allowlisting Pigment's IP addresses.

   • Port. Type the TCP port on which the server listens for SFTP connections.

   • User login. Type the username that Pigment uses to connect to the server.

   • User private key. Copy and paste the whole content of your private key file.

   • Server fingerprint. Type the fingerprint of the server, in SHA256-base64 format (see SFTP Step 3 - Getting the server SSH host key fingerprint).

   • Use PGP encryption. Select the checkbox if you want Pigment to read PGP-encrypted files.

⚠️ Important

Usernames used for SFTP connections must follow standard UNIX conventions:

• Only use letters (a–z), digits (0–9), underscores (_), or hyphens (-).

• The name must not begin with a digit or a hyphen.

• Avoid spaces and special characters.

ℹ️ Note

If you activate PGP encryption on the connector, Pigment generates a PGP encryption key and all files retrieved through this SFTP connection should be encrypted.

To retrieve the PGP encryption key, select Edit Connection after creating the connection, then copy the PGP public key using the Copy symbol.

Use the connection in Pigment

After configuring the SFTP connection, open an Application where the connection is available and select Import Data in the Block where you want to import data.

For example, to import data into a Transactions List:

1. Open the List, select Import data, and then choose Import.

2. Select the Integration option.

3. Choose your SFTP connection.

4. Select the Import mode you want. You can choose between Fixed file and Most recent file.

5. Type the file path and name for your import mode:

   • Fixed file. Type the file name and location, for example folder1/folder2/file.csv, and select Import. The file should load into Pigment within a few seconds. If you save this configuration, Pigment uploads only this file name.

   • Most recent file. Type a path that includes {{date}}, for example folderA/{{date}}-salaries.csv. Pigment uploads the most recent matching file. Your file names must follow a consistent naming convention with an ISO-8601-compatible date. For more information, see File path format and File naming convention.

File naming convention

The following table shows examples of ISO-8601-compatible date formats using a file named rev.csv.

File path format

Define the folder path first (for example, folder1/folder2/), then insert {{date}} in the file name or path. The path is case-sensitive.

folder1/folder2/prefix{{date}}suffix.csv
folder1/prefix{{date}}suffix/file.csv

Path and result examples

Example 1

Path: folderA/{{date}}-salaries.csv

Imports: /folderA/2025-10-15-salaries.csv

Selects the most recent matching file in folderA.

Example 2

Path: folderB/{{date}}-salaries.csv

Imports: /folderB/2025-11-15-salaries.csv

Selects the most recent matching file in folderB.

Example 3

Path: /{{date}}-salaries.csv

Imports: No file

Folder location is missing.