You can use the SFTP To Go API to integrate with SFTP To Go and manage SFTP To Go settings and credentials.

To programmatically access files, use SFTP, FTPS or Amazon S3 libraries.

Overview

SFTP To Go REST API conforms to the design principles of Representational State Transfer (REST). To get a running start with the API, we recommend using the curl command-line utility.

All API calls start with:
https://api.sftptogo.com/organizations/${SFTPTOGO_ORGANIZATION_ID}

The organization ID identifies an SFTP To Go instance. You can copy it from your browser’s address bar after you’ve logged in to SFTP To Go.

All API access is provided over HTTPS, and all data is sent and received in the JSON format. Make sure to add the Content-type: application/json header when passing argument data through, in an API call.

All API calls are authenticated using an API key passed in the Authorization header as such:
Authorization: Bearer ${SFTPTOGO_API_KEY}

The API Key is presented to Heroku applications in the SFTPTOGO_API_KEY environment variable.

In the following documentation, we’ll assume that the following variables have been set:

SFTPTOGO_API_KEY=<SFTPToGo API Key>
SFTPTOGO_ORGANIZATION_ID=<Organization ID>

API Reference

List Credentials

Get a list of all credentials.

GET api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users

Example:

curl --request GET \
  --url https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users \
  -H "Authorization: Bearer ${SFTPTOGO_API_KEY}" \
  -H "Content-type: application/json"

Example output:

Status: 200 OK

[
    {
        "Alias": "Root",
        "ChrootDirectory": "/",
        "CreatedAt": 1565537159609,
        "HomeDirectory": "/sftptg-prod-us-east-1-72e9cf24-be8c-4f15-9aa2-813281fb98fe",
        "Host": "warm-soda-25793.sftptogo.com",
        "Id": "4ddb2ea265b8eaf7685b4e125a1292",
        "UserName": "user-name",
        "IsDefault": true,
        "OrganizationId": "72e9cf24-be8c-4f15-9aa2-813281fb98fe",
        "Password": "my-secret-password",
        "PasswordCreatedAt": "2020-10-26T07:19:26.908Z",
        "Permission": "full",
        "Settings": {
            "Network": {
                "InboundRules": [
                    {
                        "Action": "allow",
                        "Description": "Allow all inbound traffic from anywhere",
                        "Id": "c1d91788-e46f-45a0-9c7b-386e90db000a",
                        "Protocol": "SFTP",
                        "Source": "0.0.0.0/0",
                        "State": "enabled"
                    }
                ]
            }
        },
        "SshPublicKeysCount": 1,
        "State": "active",
        "URI": "sftp://user-name:my-secret-password@warm-soda-25793.sftptogo.com",
        "UpdatedAt": 1605642318015
    }
]

Create Credentials

Create a new set of credentials

POST https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users
Parameters:

Name	Type	Description
Alias	string	Name for the credentials (not used in login).
UserName	string	User name of these credentials when connecting to your server. It must be a minimum of 10 and a maximum of 100 alphanumeric, underscore, hyphen or period characters.
Password	string	Password of these credentials when connecting to your server. It must conform to organization level password policy.
HomeDirectory	string	The user’s home directory - if the client doesn’t explicitly define otherwise, this is the user’s default directory.
ChrootDirectory	string	If set, the user will be bound to this directory and won’t be able to access any parent or sibling directories.
Permission	string	`none` - no access `read-only` - can read, but not write. `read-write` - can read and write. `write-only` - can write but not read. `full` - can read, write and access home directory.
State	string	`active` / `inactive`

Example call:

curl --request POST \
  --url https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users \
  -H "Authorization: Bearer ${SFTPTOGO_API_KEY}" \
  -H "Content-type: application/json" \
  --data '{
    "Alias": "Test Credential",
    "UserName": "my-user-name",
    "Password": "my-secret-password",
    "HomeDirectory": "/",
    "ChrootDirectory": "/",
    "Permission": "read-write",
    "State": "active"
  }'

Example output:

Status: 201 Created

{
    "Alias": "Test Credential",
    "ChrootDirectory": "/",
    "CreatedAt": 1616615059930,
    "HomeDirectory": "/",
    "Host": "warm-soda-25793.sftptogo.com",
    "Id": "cfc211269c8c0f925c64b1a223d8eb",
    "UserName": "my-user-name",
    "IsDefault": false,
    "OrganizationId": "72e9cf24-be8c-4f15-9aa2-813281fb98fe",
    "Password": "my-secret-password",
    "Permission": "read-write",
    "SshPublicKeysCount": 0,
    "Settings": {
        "Network": {
            "InboundRules": [
                {
                    "Action": "allow",
                    "Description": "Allow all inbound traffic from anywhere",
                    "Id": "c1d91788-e46f-45a0-9c7b-386e90db000a",
                    "Protocol": "SFTP",
                    "Source": "0.0.0.0/0",
                    "State": "enabled"
                }
            ]
        }
    },
    "State": "active",
    "URI": "sftp://my-user-name:my-secret-password@warm-soda-25793.sftptogo.com",
    "UpdatedAt": 1616615059930
}

Get credentials

Get a specific set of credentials.
GET https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users/$CREDENTIAL_ID

Example call:

curl --request GET \
  --url https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users/$CREDENTIAL_ID \
  -H "Authorization: Bearer ${SFTPTOGO_API_KEY}" \
  -H "Content-type: application/json"

Example response:

200 Ok

{
    "Alias": "Test Credential",
    "ChrootDirectory": "/",
    "CreatedAt": 1616615059930,
    "HomeDirectory": "/",
    "Host": "warm-soda-25793.sftptogo.com",
    "Id": "cfc211269c8c0f925c64b1a223d8eb",
    "IsDefault": false,
    "OrganizationId": "72e9cf24-be8c-4f15-9aa2-813281fb98fe",
    "Password": "my-secret-password",
    "Permission": "read-write",
    "SshPublicKeysCount": 0,
    "State": "active",
    "URI": "sftp://my-user-name:my-secret-password@warm-soda-25793.sftptogo.com",
    "UpdatedAt": 1616615059930,
    "UserName": "user-name"
}

Update credentials

Update an existing set of credentials by only passing the keys necessary to update within the data argument.
PATCH https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users/$CREDENTIAL_ID

Parameters - see (Create credentials parameters)[#createjob]

Example call:

curl --request PATCH \
  --url https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users/$CREDENTIAL_ID \
  -H "Authorization: Bearer ${SFTPTOGO_API_KEY}" \
  -H "Content-type: application/json" \
  --data '{
    "Alias": "Test Credential (updated)",
    "HomeDirectory": "/test",
    "Permission": "read-write"
  }'

Example response:

Status: 200 OK

{
    "Alias": "Test Credential",
    "ChrootDirectory": "/",
    "CreatedAt": 1616615059930,
    "HomeDirectory": "test",
    "Host": "warm-soda-25793.sftptogo.com",
    "Id": "cfc211269c8c0f925c64b1a223d8eb",
    "UserName": "user-name",
    "IsDefault": false,
    "OrganizationId": "72e9cf24-be8c-4f15-9aa2-813281fb98fe",
    "Password": "my-secret-password",
    "Permission": "read-write",
    "SshPublicKeysCount": 0,
    "State": "active",
    "URI": "sftp://my-user-name:my-secret-password@warm-soda-25793.sftptogo.com",
    "UpdatedAt": 1616615059930
}

Update credentials network inbound rules

Update network inbound rules for specific credentials. Note that this call will override any inbound rules that were previously set.

PATCH https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users/$CREDENTIAL_ID

Parameters:

Name	Type	Description
Settings.Network.InboundRules	array	A collection of network inbound rules to control which external IPs are allowed to connect to your server with these credentials.
Settings.Network.InboundRules[].Id	string	A unique identifier of the inbound rule that can be later used to identify it.
Settings.Network.InboundRules[].Protocol	string	`*` / `SFTP` / `FTPS`
Settings.Network.InboundRules[].State	string	`enabled` / `disabled`
Settings.Network.InboundRules[].Action	string	Must be set to `allow`.
Settings.Network.InboundRules[].Source	string	A single IP address, or an IP address range in CIDR notation which are allowed to connect to your server.
Settings.Network.InboundRules[].Description	string	Description for the inbound rule.

Example call:

curl --request PATCH \
  --url https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users/$CREDENTIAL_ID \
  -H "Authorization: Bearer ${SFTPTOGO_API_KEY}" \
  -H "Content-type: application/json" \
  --data '{
    "Settings": {
        "Network": {
            "InboundRules": [
                {
                    "Action": "allow",
                    "Description": "Allow all inbound traffic from anywhere",
                    "Id": "c1d91788-e46f-45a0-9c7b-386e90db000a",
                    "Protocol": "SFTP",
                    "Source": "0.0.0.0/0",
                    "State": "enabled"
                }
            ]
        }
    }
  }'

Example response:

Status: 200 OK

{
    "Alias": "Test Credential",
    "ChrootDirectory": "/",
    "CreatedAt": 1616615059930,
    "HomeDirectory": "test",
    "Host": "warm-soda-25793.sftptogo.com",
    "Id": "cfc211269c8c0f925c64b1a223d8eb",
    "UserName": "user-name",
    "IsDefault": false,
    "OrganizationId": "72e9cf24-be8c-4f15-9aa2-813281fb98fe",
    "Password": "my-secret-password",
    "Permission": "read-write",
    "SshPublicKeysCount": 0,
    "State": "active",
    "URI": "sftp://my-user-name:my-secret-password@warm-soda-25793.sftptogo.com",
    "Settings": {
        "Network": {
            "InboundRules": [
                {
                    "Action": "allow",
                    "Description": "Allow all inbound traffic from anywhere",
                    "Id": "c1d91788-e46f-45a0-9c7b-386e90db000a",
                    "Protocol": "SFTP",
                    "Source": "0.0.0.0/0",
                    "State": "enabled"
                }
            ]
        }
    },
    "UpdatedAt": 1616615059930
}

Delete credentials

Delete a specific set of credentials. Note that Root credentials cannot be deleted.
DELETE https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users/$CREDENTIAL_ID

Example call:

curl --request DELETE \
  --url https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users/$CREDENTIAL_ID \
  -H "Authorization: Bearer ${SFTPTOGO_API_KEY}" \
  -H "Content-type: application/json"

Example response:

200 Ok

{
    "Alias": "Test Credential",
    "ChrootDirectory": "/",
    "CreatedAt": 1616615059930,
    "HomeDirectory": "test",
    "Host": "warm-soda-25793.sftptogo.com",
    "Id": "cfc211269c8c0f925c64b1a223d8eb",
    "UserName": "user-name",
    "IsDefault": false,
    "OrganizationId": "72e9cf24-be8c-4f15-9aa2-813281fb98fe",
    "Password": "my-secret-password",
    "Permission": "read-write",
    "SshPublicKeysCount": 0,
    "State": "active",
    "URI": "sftp://my-user-name:my-secret-password@warm-soda-25793.sftptogo.com",
    "UpdatedAt": 1616615059930
}

Rotate password

Rotate specified credentials’ passwords. Open sessions will not be affected by password rotation. To obtain the new password, after rotation, make a get request.
POST https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users/$CREDENTIAL_ID/credential-rotations

Example call:

curl --request POST \
  --url https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users/$CREDENTIAL_ID/credential-rotations \
  -H "Authorization: Bearer ${SFTPTOGO_API_KEY}" \
  -H "Content-type: application/json"

Example response:

200 Ok

{"message":"Credentials reset."}

List public SSH keys for specific credentials

List all public SSH keys linked with existing credentials.

GET https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users/$CREDENTIAL_ID/ssh-public-keys

Example call:

curl --request GET \
  --url https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users/$CREDENTIAL_ID/ssh-public-keys \
  -H "Authorization: Bearer ${SFTPTOGO_API_KEY}" \
  -H "Content-type: application/json"

Example response:

200 Ok

[
    {
        "Comment": "ladybug@Ladybugs-MacBook-Pro.local",
        "CreatedAt": 1617354664883,
        "Fingerprint": "SHA256:RcoHnamHrApC",
        "Id": "97285e07-09fd-42de-a1d0-997a0818310a",
        "SshPublicKeyBody": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDS2KBmXgE...",
        "Type": "rsa",
        "UpdatedAt": 1617354664883,
        "UserId": "4ddb2ea265b8eaf7685b4e125a1292"
    }
]

Add SSH key

Add an SSH key to an existing set of credentials.

POST https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users/$CREDENTIAL_ID/ssh-public-keys

Parameters:

Name	Type	Description
SshPublicKeyBody	string	An SSH Public key which contains information about the type of encryption at the beginning of the string, like: `ssh-rsa`.

Example call:

curl --request POST \
  --url https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users/$CREDENTIAL_ID/ssh-public-keys \
  -H "Authorization: Bearer ${SFTPTOGO_API_KEY}" \
  -H "Content-type: application/json" \
  --data '{
    "SshPublicKeyBody": "key"
  }'

Example response:

Status: 201 Created

{
    "Comment": "ladybug@Ladybugs-MacBook-Pro.local",
    "CreatedAt": 1617354664883,
    "Fingerprint": "SHA256:RcoHnamHrApC",
    "Id": "97285e07-09fd-42de-a1d0-997a0818310a",
    "SshPublicKeyBody": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDS2KBmXgE...",
    "Type": "rsa",
    "UpdatedAt": 1617354664883,
    "UserId": "4ddb2ea265b8eaf7685b4e125a1292"
}

Remove SSH key

Remove an existing SSH key from a set of credentials.

DELETE https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users/$CREDENTIAL_ID/ssh-public-keys/$KEY_ID

Example call:

curl --request DELETE \
  --url https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users/$CREDENTIAL_ID/ssh-public-keys/$KEY_ID \
  -H "Authorization: Bearer ${SFTPTOGO_API_KEY}" \
  -H "Content-type: application/json"

Example response:

Status 200, Ok

{
    "Comment": "ladybug@Ladybugs-MacBook-Pro.local",
    "CreatedAt": 1617354664883,
    "Fingerprint": "SHA256:RcoHnamHrApC",
    "Id": "97285e07-09fd-42de-a1d0-997a0818310a",
    "SshPublicKeyBody": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDS2KBmXgE...",
    "Type": "rsa",
    "UpdatedAt": 1617354664883,
    "UserId": "4ddb2ea265b8eaf7685b4e125a1292"
}

SFTP To Go REST API

Overview

API Reference

List Credentials

Create Credentials

Get credentials

Update credentials

Update credentials network inbound rules

Delete credentials

Rotate password

List public SSH keys for specific credentials

Add SSH key

Remove SSH key

You might also like

What is SFTP?

How to add SSH keys to credentials

How to create SSH keys in Windows 10

SFTP SaaS vs. Hosted SFTP