
You use Stedi SFTP to manage the users that have access to your SFTP storage. You use Stedi Buckets to access your SFTP storage programmatically.

When you create your first Stedi SFTP user, Stedi SFTP will automatically provision a bucket for you. Whenever someone uploads a file using SFTP, it’s stored in that bucket. Whenever someone downloads a file using SFTP, it’s retrieved from that bucket. 

## Stedi Buckets

If you want to access the files in the bucket from code, you have to use Stedi Buckets. All you need is an [API key](https://www.stedi.com/app/settings/api-keys) and the name of the bucket. The bucket name is generated automatically. It’s part of the response whenever you create a new user, retrieve information about a user, or list all users.

You can access all files uploaded through Stedi SFTP using Stedi Buckets and you can access all files uploaded through Stedi Buckets using Stedi SFTP.

> See also\
> [Reference: Stedi Buckets Javascript SDK](/docs/buckets/sdk)\
> [Reference: Stedi Buckets Web API](/docs/api/buckets)

### Access rights

When you access files using Stedi Buckets, your API key determines the access rights and your API key gives you access to all files. Stedi SFTP users are not taken into account when you access files from code.

### Bucket notifications

You can use a bucket notification to invoke a Stedi function each time someone uploads a file. This allows you to kick off an automated workflow. For example, when a trading partner uploads an EDI file, the function can pick it up, call EDI Translate, and send the result to your internal API.

Bucket notifications are available for all your buckets, including the one generated by Stedi SFTP.

> See also\
> [Overview: Bucket notifications](/docs/buckets/notifications)\
> [Tutorial: Sending bucket notifications to a function](/docs/tutorials/sending-bucket-notifications-to-a-function)

## Example

```javascript
import { SftpClient, ListUsersCommand } from "@stedi/sdk-client-sftp";
import { BucketsClient, ReadBucketCommand } from "@stedi/sdk-client-buckets";

main();

async function main() {
  // Create a client that provides access to Stedi SFTP.
  const sftpClient = new SftpClient({
    region: "us",
    apiKey: process.env.STEDI_API_KEY
  });

  // Retrieve all SFTP users in an attempt to get the name of the bucket Stedi
  // SFTP has created for us.
  const listUsersCommand = new ListUsersCommand({});
  const listUsersResult = await sftpClient.send(listUsersCommand);

  if (!listUsersResult.items?.length) {
    // If there are not SFTP users, we assume there is no SFTP bucket.
    console.info("SFTP bucket doesn't exist.");
    return;
  }

  // Get the bucket name from the first user. The bucket name is the same for
  // all users.
  const bucketName = listUsersResult.items[0].bucketName;
  
  // Create a client that provides access to Stedi Buckets.
  const bucketsClient = new BucketsClient({
    region: "us",
    apiKey: process.env.STEDI_API_KEY
  });

  // Retrieve information about the SFTP bucket.
  const readBucketCommand = new ReadBucketCommand({
    bucketName: bucketName
  });
  const readBucketResult = await bucketsClient.send(readBucketCommand);
  const createdAt = new Date(readBucketResult.createdAt);
  
  // Display information about the SFTP bucket.
  console.info(
    `Bucket ${bucketName} ` +
    `was created on ${createdAt.toDateString()} ` +
    `at ${createdAt.toTimeString()}.`
  );

  const notificationCount = readBucketResult.notifications?.functions?.length;
  if (!notificationCount) {
    console.info("It has no bucket notifications.");
  }
  else {
    console.info("Bucket notifications:");
    for (const notification of readBucketResult.notifications.functions) {
      console.info(`- ${notification.functionName}`);
    }
  }
}
```

You can access the files uploaded to Stedi SFTP using Stedi Buckets.

Accessing files


When you exchange files with your trading partner using SFTP, it’s common to poll for new files. There are costs you incur with polling, regardless of whether your trading partner does the polling or you do. We have a couple of tips to keep these costs down.

## Don’t poll yourself

Your trading partners access your files using SFTP, because it allows them to use a technology they’re familiar with. You yourself shouldn’t use SFTP to access these files, though. You have direct access to your files through [Stedi Buckets](/docs/buckets) and this is cheaper than Stedi SFTP. Better yet, instead of polling, you can use [bucket notifications](/docs/buckets/notifications).

## Adjust the polling frequency

The main factor in determining the cost involved with polling, is how often your trading partner does it. The following table shows how their polling frequency influences your monthly costs, assuming a 31-day month.

| Polling frequency     | Costs per month<sup>*</sup> |
|-----------------------|-----------------------------|
| Once every 1 minute   |                       $6.70 |
| Once every 5 minutes  |                       $1.34 |
| Once every 60 minutes |                       $0.11 |

<sup>*</sup> These are the costs for the polling alone, without downloading any of the files. The actual costs may vary, as it depends on the number of files that are stored in SFTP. Which brings us to our next tip.

## Delete files you don’t need anymore

The typical scenario is that you make a file available containing a transaction and your trading partner downloads and processes it. You should tell your trading partner to delete the file once they’re done with it.

The costs vary based on the number of files, so deleting the files you don’t need anymore keeps the cost of polling down.

## Talk to your trading partner

Even though your trading partner is doing the polling, you incur the costs because the files are hosted in your Stedi account. You should talk to you trading partner and provide them with guidelines for using SFTP:

- Don’t poll more often than necessary.
- Only upload files that need to be processed.
- Only download files once.
- Delete files once they’re processed.

If your trading partner doesn’t follow these guidelines, you have the option to revoke their credentials and they will lose access to your SFTP. You can easily create new credentials for them once you’ve resolved the issue.


You can use Stedi SFTP to poll for new files. Here are some tips to keep the costs down.

Polling

## Limits

| Description                  | Default limit | Can be raised |
| ---------------------------- | ------------- | ------------- |
| Maximum number of users      | 100           | Yes           |
| Concurrent sessions per user | 10            | Yes           |
| Maximum size of file         | 5TB           | No            |


Limits

## Endpoints

### Global (US)

*   API:  `https://api.sftp.us.stedi.com/2022-04-01/`
*   Data:  `transfer.us.stedi.com`
    * FTPS port: `21`
    * SFTP port: `22`


Endpoints

With the Stedi SFTP SDK you can programmatically access Stedi SFTP.

SFTP SDK

This example shows how to use the SFTP service from the command line.

## Authentication

[Create an API key](/docs/accounts-and-billing/authentication) if you haven’t done so already. The examples on this page assume you have your API key stored in an environment variable called `STEDI_API_KEY`. You can do that with the following command.

```shell
export STEDI_API_KEY=replace.withYourOwnApiKey
```

## Create an SFTP user

Create a user by calling the Stedi SFTP API. You can customize `description`, `homeDirectory` and `passwordOptions`.

*   `description` helps you find the user account later if you need to.
*   `homeDirectory` determines which files and directory the user has access to. The user can access any file or directory
    under their home directory, but none outside of it.
*   `passwordOptions` determines how the password is generated.
    *   `length` determines the length of the password.

```shell
curl --request POST 'https://api.sftp.us.stedi.com/2022-04-01/users' \
    --header "Authorization: Key ${STEDI_API_KEY}" \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "homeDirectory": "/directory/for/partner1",
        "description": "Trading Partner 1"
    }'
```

The response will look something like this.

```json
{
  "username": "WL9F11A9",
  "homeDirectory": "/directory/for/partner1",
  "description": "Trading Partner 1",
  "bucketName": "565460e4-4c6f-4a55-87f1-a9d27616f8aa-sftp",
  "endpoint": "transfer.us.stedi.com",
  "password": "k9TqUSvZsGPs9iav"
}
```

## Connect to the SFTP endpoint

You can use the returned credentials to connect to the SFTP endpoint. You can use whichever SFTP client you prefer. In this example, we’ll access the endpoint from the command line.

```shell
sftp WL9F11A9@transfer.us.stedi.com
```

The client will ask for your password. After that, you will see the following prompt.

```
sftp>
```

You can type in commands to interact with the SFTP endpoint. If you’re not familiar with SFTP commands, here are a few common ones to get you started.

| Command  | Description                                                                          |
| -------- | ------------------------------------------------------------------------------------ |
| `pwd`    | Show the name of the active directory on the SFTP endpoint.                          |
| `lpwd`   | Show the name of the active directory on your local machine.                         |
| `ls`     | List the contents of the active directory on the SFTP endpoint.                      |
| `lls`    | List the contents of the active directory on your local machine.                     |
| `cd`     | Change the active directory on the SFTP endpoint, e.g. `cd documents`.               |
| `lcd`    | Change the active directory on your local machine, e.g. `cd documents`.              |
| `mkdir`  | Create a directory on the SFTP endpoint, e.g. `mkdir documents`.                     |
| `get`    | Download a file from the SFTP endpoint to your local machine, e.g. `get file.txt`.   |
| `put`    | Upload a file from your local machine to the SFTP endpoint, e.g. `put file.txt`.     |
| `rename` | Change the name of a file on the SFTP endpoint, e.g. `rename file.txt document.txt`. |
| `rm`     | Remove a file from the SFTP endpoint, e.g. `rm document.txt`.                        |
| `bye`    | Disconnect from the SFTP endpoint.                                                   |


Using Stedi SFTP from the command line

This example shows how to use the Stedi SFTP SDK. This is of use to JavaScript developers who want to generate SFTP
credentials programmatically, but don't want to interact with the Stedi SFTP API directly.

## Authentication

[Create an API key](/docs/accounts-and-billing/authentication) if you haven’t done so already. The examples on this page assume you have your API key stored in an environment variable called `STEDI_API_KEY`. You can do that with the following command.

```shell
export STEDI_API_KEY=replace.withYourOwnApiKey
```

## Install the SDK

The following code examples are in Javascript only.
We offer the Stedi SDK for JavaScript (we also provide TypeScript support). To get started, install the
[@stedi/sdk-client-sftp](https://www.npmjs.com/package/@stedi/sdk-client-sftp) package.
You can do this by running `npm install --save @stedi/sdk-client-sftp` in your local
directory. Please note that to run the following examples you need to install [node@16](https://nodejs.org/en/download/)
or higher.

## Create an SFTP user

Create a user. You can customize `description`, `homeDirectory` and `passwordOptions`.

*   `description` helps you find the user account later if you need to.
*   `homeDirectory` determines which files and directory the user has access to. The user can access any file or directory
    under their home directory, but none outside it.
*   `passwordOptions` determines how the password is generated.
    *   `length` determines the length of the password.

```javascript
const stediSftpSdk = require("@stedi/sdk-client-sftp");

const apiKey = process.env.STEDI_API_KEY; // Fetch your API key from an environment variable.

// Create a new SFTP Client for the Stedi US region
const stediSftpClient = new stediSftpSdk.SftpClient({
  region: "us",
  apiKey: apiKey,
});

// Create an SFTP user for Alice
const createUserOutput = await stediSftpClient.send(
  new stediSftpSdk.CreateUserCommand({
    description: "Trading partner Alice",
    homeDirectory: "/alice",
  }),
);

// Print the user object
console.log(createUserOutput);
```

The response will look like this.

```json
{
  "username": "WL9F11A9",
  "homeDirectory": "/alice",
  "description": "Trading partner Alice",
  "bucketName": "565460e4-4c6f-4a55-87f1-a9d27616f8aa-sftp",
  "endpoint": "transfer.us.stedi.com",
  "password": "k9TqUSvZsGPs9iav"
}
```

## Connect to the SFTP endpoint

Alice can use the returned credentials to connect to the SFTP endpoint using whichever SFTP client she prefers. We
provide an example using the command line SFTP client
here: [command line example](/docs/sftp/using-stedi-sftp-from-the-command-line)


Using Stedi SFTP with the SDK

Stedi SFTP provides fully managed, serverless SFTP infrastructure that supports SFTP and FTPS protocols.You can use Stedi SFTP to securely exchange files with trading partners without having to worry about setting up servers or provisioning capacity. Stedi SFTP scales instantly, on demand to an unlimited number of trading partners and an unlimited number of files.

## How it works

Your Stedi account gives you access to a Stedi-hosted SFTP endpoint. In a couple of clicks, you can create a user
using [the SFTP UI](https://www.stedi.com/app/sftp). The user will have access to the SFTP endpoint, but only to
files that are within the directory that you assign to them. You can also create users programmatically at
scale [via the API](/docs/sftp/using-stedi-sftp-from-the-command-line)
or [using the SDK](/docs/sftp/using-stedi-sftp-sdk).

## Use cases

Here are some common use cases for SFTP:

*   **Exchange files with your trading partners.** Create an SFTP user with a unique home directory for each of your
    trading partners, and share the credentials with them. They can then upload and download files in that directory through
    SFTP or FTPS. 
*   **Process uploaded documents using Stedi Functions.** You can [access uploaded documents](/docs/sftp/accessing-files) using Stedi Buckets.
    The bucket can be configured to [automatically invoke a Stedi Function whenever a new
    document is uploaded](/docs/sftp/accessing-files#bucket-notifications).

## Getting started

To get started with SFTP, use one of the following methods.

### Using the UI

*   **[Create a Stedi account](/terminal/sign-up)** (free and no credit card required).
*   **[Create an SFTP user in the UI](/app/sftp/create).**

### Using the command line

You can also do this [from the command line](/docs/sftp/using-stedi-sftp-from-the-command-line).

### Using the SDK

We publish a JavaScript SDK, which you can use to [create and manage SFTP users](/docs/sftp/using-stedi-sftp-sdk).

## Automatically provisioned resources:

When you create an SFTP user the following resources are automatically provisioned, if they don't already exist:
*    An SFTP-enabled [Stedi bucket](/docs/buckets)
*    The home directory specified for the user (for any home directory other than the root directory `/`) 

## Permissions

SFTP users have a home directory. They can access any file or directory under their home directory, but none outside it.
In order to exchange files with your trading partners Alice and Bob, you could provision the following users:

### Alice

*   description: `Trading partner Alice`
*   home directory: `/alice`

### Bob

*   description: `Trading partner Bob`
*   home directory: `/bob`

Next, provision a root user which you can use to access files in each of the trading partners’ home directories.

### Root

*   description: `Root user`
*   home directory: `/`

Alice and Bob will only be able to upload and download files in their home directories. Root will have access to all files, and can
be used to upload and download documents for all trading partners.


Request timed out while provisioning the Bucket resource.

Request timed out while provisioning the SFTP resource.

The Stedi account has not been granted permission for this particular service.

Describes one specific validation failure for an input member.

A standard error for input validation failures.
This should be thrown by services when a member of the input structure
falls outside of the modeled or documented constraints.

Stedi SFTP provides a fully managed, serverless SFTP infrastructure. You can use the SFTP API to manage SFTP users.

> For [accessing files programmatically](/docs/sftp/accessing-files), you should use the [Stedi Buckets SDK](/docs/buckets/sdk).

SFTP

Feedback