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

Credentials

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 HomeDirectory will be mapped to this value (For example, you could set the HomeDirectory to /sales and ChrootDirectory to /ventas, in which case, when the user connects, they will find a single directory they can access, called /ventas, which maps to the actual /sales directory). Default value is / (meaning that the users start within their assigned HomeDirectory.
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.
Expiration	int	The date (in unix time) after which these credentials will automatically become inactive. If left blank, they will never expire
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

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."}

Public SSH Keys

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"
}

Webhooks

List webhooks

Get a list of all webhooks.

Example:

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

Example output:

Status: 200 OK

[
    {
        "Id": "6b1c6f0c-52c1-47a6-9344-57a4579ced68",
        "Alias": "Test Webhook",
        "Url": "https://webhook.site/1b1b1b1b-1b1b-1b1b-1b1b-1b1b1b1b1b1b",
        "Type": "webhook",
        "AuthorizationHeader": "Bearer 123456789",
        "Secret": "",
        "Topics": ["file.created", "file.deleted", "file.downloaded"],
        "OrganizationId": "120ffd28-f115-7ce2-abc4-1e168c57c88a",
        "State": "enabled",
        "CreatedAt": 1561888254653,
        "UpdatedAt": 1561888254653
    }
]

Create webhook

Create a new webhook.

POST https://api.sftptogo.com/organizations/$ORGANIZATION_ID/webhooks

Parameters:

Name	Type	Description
Alias	string	Name for the webhook
Url	string	For Webhook, this should be a valid HTTPS URL that will receive webhook notifications. For Slack and Teams, this should be a valid incoming webhook URL. For Email, this should be a valid email address.
Type	string	webhook - https webhook slack - Slack incoming webhook ms-teams - Microsoft Teams webhook email - email webhook
AuthorizationHeader	string	Optional authorization header
Topics	array	Array of topics to subscribe to: file.created - file created file.deleted - file deleted file.downloaded - file downloaded
State	string	enabled or paused

Example call:

curl --request POST \
  --url https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/webhooks \
  -H "Authorization: Bearer ${SFTPTOGO_API_KEY}" \
  -H "Content-type: application/json" \
  --data '{
    "Alias": "Test Webhook",
    "Url": "https://webhook.site/1b1b1b1b-1b1b-1b1b-1b1b-1b1b1b1b1b1b",
    "Type": "webhook",
    "AuthorizationHeader": "Bearer 123456789",
    "Topics": ["file.created", "file.deleted", "file.downloaded"],
    "State": "enabled"
  }'

Example output:

Status: 201 Created

{
    "Id": "6b1c6f0c-52c1-47a6-9344-57a4579ced68",
    "Alias": "Test Webhook",
    "Url": "https://webhook.site/1b1b1b1b-1b1b-1b1b-1b1b-1b1b1b1b1b1b",
    "Type": "webhook",
    "AuthorizationHeader": "Bearer 123456789",
    "Secret": "Some Secret",
    "Topics": ["file.created", "file.deleted", "file.downloaded"],
    "OrganizationId": "120ffd28-f115-7ce2-abc4-1e168c57c88a",
    "State": "enabled",
    "CreatedAt": 1561888254653,
    "UpdatedAt": 1561888254653
}

Update webhook

Update an existing webhook. In the argument JSON, only pass the keys necessary to update.

Parameters - see Create webhook parameters

curl --request PATCH \
  --url https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/webhooks/$WEBHOOK_ID \
  -H "Authorization: Bearer ${SFTPTOGO_API_KEY}" \
  -H "Content-type: application/json" \
  --data '{
    "Alias": "Test Updated Webhook"
  }'

Example output:

Status: 200 OK

{
    "Id": "6b1c6f0c-52c1-47a6-9344-57a4579ced68",
    "Alias": "Test Updated Webhook",
    "Url": "https://webhook.site/1b1b1b1b-1b1b-1b1b-1b1b-1b1b1b1b1b1b",
    "Type": "webhook",
    "AuthorizationHeader": "Bearer 123456789",
    "Secret": "Some Secret",
    "Topics": ["file.created", "file.deleted", "file.downloaded"],
    "OrganizationId": "120ffd28-f115-7ce2-abc4-1e168c57c88a",
    "State": "enabled",
    "CreatedAt": 1561888254653,
    "UpdatedAt": 1561888254653
}

Delete webhook

Delete an existing webhook.

DELETE https://api.sftptogo.com/organizations/$ORGANIZATION_ID/webhooks/$WEBHOOK_ID

Example call:

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

Example response:

200 OK

{}

We Value Your Feedback

Your insights are well received and highly prized at SFTP To Go, and they’re central to our continuous innovation.

We keep improving thanks to your user feedback and insightful feature requests.

Feel welcome to share your experiences and suggestions through our in-app chat. Every bit of your feedback helps us better serve your needs.