sftp icon


Version: latest

When you want to send and receive a large amount of files via the AS2 Gateway, using an integration mechanism is a must. SFTP is one such integration mechanisms currently supported by the AS2 Gateway.

What is SFTP?

SFTP, which stands for SSH File Transfer Protocol, or Secure File Transfer Protocol, is a separate protocol packaged with SSH that works in a similar way over a secure connection. The advantage is the ability to leverage a secure connection to transfer files and traverse the filesystem on both the local and remote system.

The AS2 Gateway runs an SFTP server and once the SFTP setup is done, users can login to the AS2 Gateway’s SFTP server to download received files and upload files to be sent.

If you enable SFTP integration, messages in your web interface will be only retained for a maximum period of 60 days.
Attachments placed into SFTP are not guaranteed to be available beyond 48 hours; hence it is recommended to fetch the received files at least within 24 hours, and delete each file from AS2 Gateway SFTP space as soon as it is retrieved. AS2 Gateway SFTP space must not be used for long-term storage of your attachments/files.

Setup SFTP with AS2 Gateway

Lets start with setting up SFTP for your account. First go to the SFTP view using the "SFTP" icon on the left navigation menu. Alternatively click on the link https://console.as2gateway.com/sftp to navigate to the SFTP view.

sftp menu

One you navigate to the SFTP view, if you haven’t already done the SFTP setup, a form will be shown with a username and a password field.

Please provide a user name and a password and click on Setup SFTP to initiate the SFTP setup.

Username should start from a lowercase character and it can only include numbers 0-9, hyphen and underscore. Uppercase characters are not allowed.

Minimum length for the password field is 5 characters.

Once you click on the "Setup SFTP" button, what happens in the background is that a key-based authentication for SFTP will be setup for you and your private key will be available for you to download after the setup. Note that the password which you provided during the setup will be the passphrase for your private key.

If you are already subscribed and paying for the Personal package: once SFTP is activated, make sure to inform AS2 Gateway Team to get your subscription updated.

Logging in to AS2 Gateway SFTP Space

Once the SFTP setup is complete, you should be able to use any of the SFTP clients and connect to the AS2 Gateway server. After the setup the SFTP view will show the instructions on connecting to the AS2 Gateway SFTP server via the command line for Linux and MacOS users. In this documentation we will cover steps on configuring connectivity using several SFTP clients including OpenSSL command line client and File Zilla and WinSCP.

A complete listing of SFTP clients can be found at https://www.sftp.net/clients

SFTP Folder Structure

Once logged in, you will be inside your own SFTP space, containing the following:

  • as2gateway: base folder containing AS2 folder/attachment hierarchy

  • id_rsa_<username>, id_rsa_<username>.pub: your SFTP private/public keys

  • .ssh: folder containing your SFTP login configurations

Within as2gateway, you can find folder path combinations for all your trading stations and partners:

<station AS2 identifier>/<partner AS2 identifier>

Under each path, there are 3 folders:

  • inbox: attachments from incoming AS2 messages

  • outbox: folder to place attachments in order to send them out as AS2 messages

  • failed: send-out attachments (from outbox) that could not be enqueued for delivery, due to some reason (error)

For more details and examples, refer to the SFTP folder structure reference.

Sending and Receiving files via SFTP

Receiving files (AS2 message attachments) via partner inbox

When a new AS2 message is received, AS2 Gateway will persist its attachments into SFTP, under your <recipient station ID>/<sender partner ID>/inbox folder.

Based on the SFTP inbox folder structure config of your AS2 station, the files may get saved in one of two ways:

  • With Create a new timestamp-prefixed folder for each incoming message, files for each incoming message will be saved into its own timestamp-prefixed subfolder:

    <SFTP root dir>/
       |__<station ID>/
          |__<partner ID>/
                |__<message processed timestamp>-<random number>/
                   |__<original attachment filename>
  • With Store incoming files at inbox root, adding a timestamp-based unique prefix to its original name, there will be no per-message subfolder; instead, everything will be saved in inbox itself, with a timestamp-based unique prefix being prepended to the original attachment filename:

    <SFTP root dir>/
       |__<station ID>/
          |__<partner ID>/
                |__<message processed timestamp>-<random number>-<original attachment filename>

Sending files (messages) out via partner outbox

There are two modes of sending files out:

  • To send a single file as an AS2 message, simply upload the file to the respective outbox. AS2 Gateway will pick it up and queue it for delivery, within a maximum of 30 seconds.

  • To send multiple files in a single AS2 message (multiple-attachment mode),

    • create a folder inside the outbox, and

    • place all files into it.

You can add up to 10 files per message, adding up to a total size of 10 MB.

In the latter case, AS2 Gateway will process and enqueue the folder content, two (2) minutes after the last file is uploaded.

Resetting SFTP

If you wish to stop using SFTP, or completely reset the SFTP space with a new keypair and clean (empty) folder structure,

SFTP integration details pane

After reset, any previously downloaded SFTP access keys would no longer work.

If you only want to change your SFTP keypair or key passphrase, DO NOT use the reset option; instead, contact AS2 Gateway Team.
If you are already subscribed and paying for the Personal package: if you do not wish to use SFTP again after the reset, make sure to inform AS2 Gateway Team to get your subscription downgraded accordingly.
In this topic
In this topic