You can use an SFTP connection (also known as a jail) to securely transfer file-based spend data between Perk and your third-party systems. You can use the Perk SFTP server to import master data (i.e. card transactions etc.) into Perk 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 Perk’s FTP server), and
• how the file uploaded to the secure directory is processed by Perk’s services and imported into the system.

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

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 Settings > Developer tools > Spend tools, SFTP connections, you can view the setup but you cannot change any details. If you need to adjust the configuration, you must reach out to Perk.

Setting up a SFTP connection

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

Note: To view the SFTP connection tab in Settings > Developer tools > Spend tools, your organization must have been enabled for SFTP. If you do not see it, reach out to Perk Support.

Authentication via SSH key

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

The SFTP username must be unique and must contain all lowercase (in other words, 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, Perk supports these ciphers:

SSH key validation

When you paste the SSH public key in the SSH key field, Perk 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 Settings > Developer tools > Spend tools, 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 Perk 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.

Viewing the SFTP connection details

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

• Perk role: Role of Perk in the connection, either server or host. For SFTP connections on Perk’s server, it is Server. Otherwise, it is Client.
• Username: User name that applications use to access the secure directory in the Perk SFTP server.
• Host name: Server address (or URL) of the server. Perk‘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 is usually Public key (SSH key authentication). For existing configurations, Password (password authentication) may have been used. However, Perk recommends you use SSH key 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.

Setting up the secure directory structure

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

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 Perk.
• 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.