AWS Transfer for SFTP
User Guide

Welcome to the AWS Transfer for SFTP API

AWS Transfer for SFTP is a fully managed service that enables the transfer of files over the Secure File Transfer Protocol (SFTP) directly into and out of Amazon Simple Storage Service (Amazon S3). AWS Transfer helps you migrate your SFTP-based file transfer workflows to AWS without disruption for your external partners and customers.

To use the AWS SFTP service you instantiate an SFTP server in the region of your choice. You can create the server, list available servers, update and delete servers. The server is th entity that requests file operations from the AWS SFTP service. Servers have a number of important properties. The server is a named instance as identified by a system assigned ServerId identifier. You can optionally assign a hostname, or even a custom hostname to a server. The service bills for any instantiated servers (even ones not ONLINE, and for the amount of data transferred.

SFTP users must be known to the SFTP server that requests file operations. A user as identified by their username is assigned to a server. User names are used to authenticate requests. A server can have only one authentication method, either SERVICE_MANAGED or API_GATEWAY. For SERVICE_MANAGED an SSH Public key is stored with the user's properties on an SFTP server. A user can have one or more SSH Public keys on file for the SERVICE_MANAGED authentication method. When an SFTP client requests a file operation for SERVICE_MANAGED method the SFTP client provides the user name and SSH Private key, which is authenticated and access is provided.

You can also authenticate user requests using a custom authentication method that provides both user authentication and access. This method relies on the Amazon API Gateway to use your API call from your Identity Provider to validate user requests. This method is referred to as API_GATEWAY in API calls, and as "Custom" in the console. You might use this custom method to authenticate users against a directory service, a database name/password pair, or some other mechanism.

SFTP users are assigned a policy with a trust relationship between themselves and an Amazon S3 bucket. They might be able to access all or part of a bucket. In order for an SFTP server to act on a user's behalf the server must inherit the trust relationship from the user. An IAM role is created that contains the trust relationship, and that role is assigned an AssumeRole> action. The SFTP server is then able to perform file operations as if it was the user. Users who have a home directory property set will have that directory (or folder) act as the target and source of SFTP file operations. When no home directory is set, the bucket's root directory becomes the landing directory.

Servers, users, and roles are all identified by their Amazon Resource Number or ARN. You can assign tags, which are key/value pairs to entities with an ARN, and tags are metadata that can be used to group or search for these entities. One example where tags are useful is for accounting purposes.

The following conventions are observed in AWS SFTP ID formats:

  • ServerId values take the form s-01234567890abcdef.

  • PublicKeyId values take the form key-12345678.

  • UserId values take the form user-12345678

Amazon Resource Number (ARN) formats take the following form:

  • For servers, Amazon Resource Names (ARNs) take the form arn:aws:transfer:region:account-id:server/server-id/.

    An example of a server ARN is: arn:aws:transfer:us-east-1:123456789012:server/s-01234567890abcdef.

  • For users, ARNs take the form arn:aws:transfer:region:account-id:user/server-id/username.

    An example is arn:aws:transfer:us-east-1:123456789012:user/s-01234567890abcdef/user1.

DNS entries (endpoints) in use are:

  • API endpoints take the form transfer.region.amazonaws.com.

  • Protocol endpoint take the form server.transfer.region.amazonaws.com

  • Server endpoints take the form server.transfer.region.amazonaws.com.

This API interface reference for AWS SFTP contains documentation for a programming interface that you can use to manage AWS SFTP. The reference structure is as follows:

  • For the alphabetical list of API actions, see API Actions.

  • For the alphabetical list of data types, see Data Types.

  • For a list of common query parameters, see Common Parameters.

  • For descriptions of the error codes, see Common Errors.