Skip to main content

Set up an SFTP connection for file exchange

If you want to transfer data to and from Yokoy using files, you can use Yokoy's SFTP server to store the files.

Yokoy Team avatar
Written by Yokoy Team
Updated over 2 weeks ago

🌐 Web | 👤 Developer

You can use an SFTP connection (aka “jail”) to securely transfer file-based data between Yokoy and your third-party systems. You can use the Yokoy SFTP server to import master data (i.e. users, cost centers, tags, card transactions etc.) into Yokoy and export financial data to an external system.

To set up an SFTP connection for file exchange, you need to determine:

  • where the file exchange takes place (in Yokoy’s FTP server), and

  • how the file uploaded to the secure directory is processed by Yokoy’s services and imported into the system (“wiring").

To host the file exchange with Yokoy, Yokoy uses an Azure SFTP server. The server is partitioned to provide secure directories (“jails”) for each customer.

✏️ Note

Make sure to add Yokoy’s SFTP IP addresses to your company‘s approve list:

🚧 Caution

If your SFTP connection was set up by Yokoy, you may find that the host name is fe.yokoy.ai rather than exchange.yokoy.ai, as it uses Yokoy’s previous SFTP server. This server is still maintained for specific customers.

If this is your case, the IP address to add to your company‘s approve list is fe.yokoy.ai (34.65.67.218).

In Admin > Developers, SFTP connection, you can view the setup but you cannot change any details. If you need to adjust the configuration, you must reach out to Yokoy.

Setting up a SFTP connection

First you need to set up the connection credentials before you can start to transfer files. Yokoy uses an Azure server to provide secure file exchange. To authenticate against the server, you can use either SSH key or a password.

🚧 Caution

Yokoy recommends you use SSH key encryption for secure access.

✏️ Note

To view the SFTP connection tab in Admin > Developers, your organization must have been enabled for SFTP. If you do not see it, reach out to Yokoy Support.

Authentication via SSH key

You can use public key authentication when connecting to the Yokoy server.

The SFTP username must be unique and must contain all lowercase (i.e. no capital letters), no underscores, no dashes, no spaces. For the public key, the expected format is OpenSSHG.

💡 Tip

You can convert the current key into the needed format via the following command line:
​ssh-keygen -i -f oldkey > newkey

You should use a modern cipher to generate your public SSH key. More specifically, Yokoy supports these ciphers:

Cipher

Host key algorithms

  • ssh-ed25519

  • ssh-rsa

  • ssh-dss

  • ecdsa-sha2-nistp256

  • ecdsa-sha2-nistp384

  • ecdsa-sha2-nistp521

SSH key validation

When you paste the SSH public key in the SSH key field, Yokoy checks:

  • If the key contains a valid number of elements: A correctly generated public SSH key consists of these parts:

    • Key type: Specifies the algorithm used to generate the key pair such as ssh-rsa for RSA keys, ssh-dss for DSA keys, or ecdsa-sha2-nistp256 for ECDSA keys.

    • Key data: This is the actual public key data. It is typically a long string of characters, which is used for encryption or signature verification.

    • Key comment (Optional): An optional field that you use to annotate the key with additional information such as an email address or a description of where the key is used.

Example of a public key
​

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQC34FvmaZ5Rf4dY1BvQh0nWzG8n... user@example.com

  • ssh-rsa represents the key type.

  • AAAAB3NzaC1yc2EAAAADAQABAAACAQC34FvmaZ5Rf4dY1BvQh0nWzG8n... is the key data.

  • user@host is the key comment.

  • If the SSH key begins with the right structure: An SSH key must start with the encryption method. Common examples are: 

  'ssh-ed25519',   'ssh-rsa',   'ssh-dss',   'ecdsa-sha2-nistp256',   'ecdsa-sha2-nistp384',   'ecdsa-sha2-nistp521'

  • If the SSH key is a string or not: An SSH key must be a string; otherwise, it is not accepted.

To set up authentication using SSH key:

  1. Go to Admin > Developer, SFTP connections tab.

  2. Click +Add SFTP connection.

  3. Enter the SFTP username. The SFTP username is a unique reference for the customer directory in the SFTP server. You should use a name that identifies the organization (e.g. companya).

  4. Paste your SSH key and make sure the key format and structure does not fail any of the checks performed.

  5. Click Complete setup.

The process to create the secure directory on the SFTP server takes approximately 24 hours. Don‘t try to access the Yokoy SFTP server in the meantime to perform end-to-end tests as the connection will be refused.

After 24 hours, the warning message above the SFTP connection details automatically disappears, letting you know that you can access the server.

Authentication via password

Although it is recommended that you use SSH key pairs to authenticate with the Yokoy server, you can set up password authentication if required.

✏️ Note
If you set up password authentication and want to change it to authentication via SSH key at a later stage, you need to open a support ticket.

To secure access, you need to specify the IP addresses from which a client can access the server.

The SFTP username must be all lowercase with no capital letters, dashes or spaces. It must be unique.

To set up authentication via password:

  1. Go to Admin > Developer, SFTP connections tab.

  2. Click +Add SFTP connection.

  3. Select Set up login with password to choose an alternative authorization mechanism.

  4. Enter the SFTP username. The SFTP username is a unique reference for the customer directory in the SFTP server. You should use a name that identifies the organization (e.g. companya)

  5. Add one or multiple IP addresses. The IP addresses determines the IPs from which the Yokoy SFTP server can be accessed. Any connections from IPs not on the allow list are refused.

  6. Click Generate password to create the secure directory using password authentication mechanism.

  7. Yokoy automatically generates a password of random characters to use to authenticate on the server. You can view the password and copy it using the corresponding icons.

✏️ Note

Make sure to copy the password and store it somewhere safe.

The process to create the secure directory on the SFTP server takes approximately 24 hours. Do not attempt to access the Yokoy SFTP server to perform end-to-end tests as the connection is refused. After 24 hours, the warning message above the SFTP connection details automatically disappears, letting you know that you can access the server.
​

Viewing the SFTP connection details

You can view the details of the SFTP connection once created. If Yokoy set up the SFTP connection for your company, you can view the details here.

  • Yokoy role: Role of Yokoy in the connection, either server or host. For SFTP connections on Yokoy’s server, it is Server. Otherwise, it is Client.

  • Username: User name that applications use to access the secure directory in the Yokoy SFTP server.

  • Host name: Server address (or URL) of the server. Yokoy‘s SFTP facility (exchange.yokoy.ai).

  • Port: Port at which the server listens to client requests. By default, port 22 is used as SFTP runs over the SSH protocol.

  • Credential type: Authentication method for accessing the SFTP connection. This can be either Public key (SSH key authentication) or Password (password authentication)

  • Public Key: For SSH key authentication, public SSH key that is associated with the client on the SFTP server.

  • Allowed IP addresses: For password authentication, the IPs that can connect to the secure directory. If you have more than one, you see Multiple. Click Multiple to display a full list of the IPs.

Edit the SFTP SSH key

You can modify the SSH key of an SFTP connection by clicking Edit at the top of the SFTP details.

You can enter the new SSH key in the SSH key field. When done, click Save.

It takes 24 hours to update the new details, so you may need to wait before trying to connect again with the new details.

Edit the allowed IP addresses and request a new password

You can add or modify the list of approved IPs by clicking Edit at the top of the SFTP details.

There are two options:

  • Add/modify the allowed IP addresses: this allows you to add or remove any IPs used to connect to the SFTP facility.

  • Request a new password to connect: If you forget the password to access your SFTP secure directory, you can always request a new one by clicking Request new password. Make sure to copy the new one and store it somewhere safe. Click Save to confirm your new password.

Setting up the secure directory structure

When the SFTP connection has been established, you can use your credentials to connect to the Yokoy SFTP server and set up the file exchange configuration.

✏️ Note

The SFTP server is rebuilt daily at approximately 20:00:00 UTC. This process takes about 5 minutes. It may mean that you are unable to connect during this time.

In general, it always advisable to keep a consistent naming and structure of folders:

  • to_yokoy folder for files that need to be imported or are sent to Yokoy.

  • from_yokoy in the event that you fetch finance data as part of a file-based integration.

  • one sub-folder per legal entity or use a legal entity identifier in the file name.

Do not modify any directory or filesystem permissions. During the daily build of the SFTP server, a script is run to reset all permissions. If you modify any permissions, this may mean that you cannot access the server for 20 minutes while the script is being run.

Did this answer your question?