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/${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>
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",
        "IsDefault": true,
        "OrganizationId": "72e9cf24-be8c-4f15-9aa2-813281fb98fe",
        "Password": "CHeo2580VkT7s9UgxPG31v93zVZMbC7xFIAaqEJX",
        "PasswordCreatedAt": "2020-10-26T07:19:26.908Z",
        "Permission": "full",
        "SshPublicKeysCount": 1,
        "State": "active",
        "URI": "sftp://4ddb2ea265b8eaf7685b4e125a1292:CHeo2580VkT7s9UgxPG31v93zVZMbC7xFIAaqEJX@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).
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",
    "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",
    "IsDefault": false,
    "OrganizationId": "72e9cf24-be8c-4f15-9aa2-813281fb98fe",
    "Password": "0hzw7ztvcrf245f6718pf0g0uyzi68nktlaco9rc",
    "Permission": "read-write",
    "SshPublicKeysCount": 0,
    "State": "active",
    "URI": "sftp://cfc211269c8c0f925c64b1a223d8eb:0hzw7ztvcrfi45fs718pf0g0uyzi68nktlaco9rb@warm-soda-25793.sftptogo.com",
    "UpdatedAt": 1616615059930,
    "UserName": "cfc211269c8c0f925c64b1a223d8eb"
}

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": "0hzw7ztvcrf245f6718pf0g0uyzi68nktlaco9rc",
    "Permission": "read-write",
    "SshPublicKeysCount": 0,
    "State": "active",
    "URI": "sftp://cfc211269c8c0f925c64b1a223d8eb:0hzw7ztvcrfi45fs718pf0g0uyzi68nktlaco9rb@warm-soda-25793.sftptogo.com",
    "UpdatedAt": 1616615059930,
    "UserName": "cfc211269c8c0f925c64b1a223d8eb"
}

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",
    "IsDefault": false,
    "OrganizationId": "72e9cf24-be8c-4f15-9aa2-813281fb98fe",
    "Password": "0hzw7ztvcrf245f6718pf0g0uyzi68nktlaco9rc",
    "Permission": "read-write",
    "SshPublicKeysCount": 0,
    "State": "active",
    "URI": "sftp://cfc211269c8c0f925c64b1a223d8eb:0hzw7ztvcrfi45fs718pf0g0uyzi68nktlaco9rb@warm-soda-25793.sftptogo.com",
    "UpdatedAt": 1616615059930,
    "UserName": "cfc211269c8c0f925c64b1a223d8eb"
}

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",
    "IsDefault": false,
    "OrganizationId": "72e9cf24-be8c-4f15-9aa2-813281fb98fe",
    "Password": "0hzw7ztvcrf245f6718pf0g0uyzi68nktlaco9rc",
    "Permission": "read-write",
    "SshPublicKeysCount": 0,
    "State": "active",
    "URI": "sftp://cfc211269c8c0f925c64b1a223d8eb:0hzw7ztvcrfi45fs718pf0g0uyzi68nktlaco9rb@warm-soda-25793.sftptogo.com",
    "UpdatedAt": 1616615059930,
    "UserName": "cfc211269c8c0f925c64b1a223d8eb"
}

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