SFTP To GoのREST APIについて

Tomotaka Endo -

SFTP To GoのAPIを使ってSFTP To Goと統合し、SFTP To Goの設定や認証情報を管理することができます。

プログラムでファイルにアクセスする場合は、SFTP、FTPS、Amazon S3ライブラリを使いましょう。

概要

SFTP To GoのREST APIは、 REST（Representational State Transfer） のデザイン原則に準拠しています。APIを使い始めるには、 curlのコマンドラインユーティリティの使用をお勧めします。

API呼出は、全て以下で始まります：
https://api.sftptogo.com/organizations/${SFTPTOGO_ORGANIZATION_ID}

組織のIDは、SFTP To Goのインスタンスを識別するものであり、SFTP To Goにログインした後、ブラウザのアドレスバーからコピーできます。

API アクセスは全て HTTPSで提供され、データは全てJSONのフォーマットで送受信されます。API呼び出しで引数データを渡す際には、必ずContent-type: application/jsonのヘッダを追加してください。

API呼び出しは、全てAuthorizationのヘッダーで渡されるAPIキーを使って、以下ように認証されます：Authorization: Bearer ${SFTPTOGO_API_KEY}

APIキーは、HerokuアプリケーションにSFTPTOGO_API_KEY環境変数で提示されます。

以下のドキュメントでは、以下の変数が設定されているものとします：

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

API参照

認証情報の一覧表示

全認証情報のリストを取得します。

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

例：

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

出力例：

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

認証情報の作成

新しい認証情報のセットを作成します。

POST https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users
パラメータ:

名称 タイプ 概要
Alias string 認証情報の名前（ログインでは使用しない）。
UserName string サーバーに接続する際の、認証情報のユーザー名。英数字、アンダースコア、ハイフン、ピリオドで１０文字から１００文字まででないといけない。
Password string サーバーに接続する際の、認証情報のパスワード。組織レベルのパスワードポリシーに準拠しないといけない。
HomeDirectory string ユーザーのホームディレクトリ - クライアントが明示的に確定していない場合は、これがユーザーのデフォルトディレクトリとなる。
ChrootDirectory string 設定された場合、ユーザーはこのディレクトリにバインドされ、親ディレクトリや兄弟ディレクトリへのアクセスができなくなる。
Permission string none - アクセス不可
read-only - 読み取り可能、書き込み不可
read-write - 読み取りおよび書き込み可能
write-only - 書き込みのみ可能、読み込み不可
full - ホームディレクトリの読み取り、書き込み、アクセスが可能
State string 有効 / 無効

呼出例：

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

出力例：

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 https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users/$CREDENTIAL_ID

呼出例：

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"

応答例：

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

認証情報の更新

Data引数で更新に必要なキーだけを渡して、既存の認証情報のセットを更新します。
PATCH https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users/$CREDENTIAL_ID

パラメータ - (Create credentials parameters)[#createjob]を確認

呼出例

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

応答例：

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
}

認証情報のネットワーク受信ルールの更新

特定の認証情報に対するネットワーク受信ルールを更新します。この呼び出しは、以前に設定された受信ルールを上書きすることに注意しましょう。

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

パラメータ：

名称 タイプ 概要
Settings.Network.InboundRules array どの外部IPがこの認証情報を使って、サーバーへの接続を許可されるかをコントロールするための、ネットワーク受信ルールの集まり。
Settings.Network.InboundRules[].Id string インバウンドルールの一意の識別子で、後で識別するのに使用できる。
Settings.Network.InboundRules[].Protocol string * / SFTP / FTPS
Settings.Network.InboundRules[].State string 有効 / 無効
Settings.Network.InboundRules[].Action string allowに設定されないといけない
Settings.Network.InboundRules[].Source string サーバーへの接続を許可する単一の IP アドレス、または CIDR 表記の IP アドレス範囲。
Settings.Network.InboundRules[].Description string 受信ルールの説明。

呼出例：

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

応答例：

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 https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users/$CREDENTIAL_ID

呼出例：

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"

応答例：

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
}

パスワードのローテーション

指定した認証情報のパスワードをローテーション（変更）させます。開いているセッションには、パスワードのローテーションの影響を受けません。ローテーション後に新しいパスワードを取得するには、GETリクエストを行います。
POST https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users/$CREDENTIAL_ID/credential-rotations

呼出例：

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"

応答例：

200 Ok

{"message":"Credentials reset."}

特定の認証情報の公開SSHキーを一覧表示する

既存の認証情報にリンクされているパブリックSSHキーを全てリストアップします。

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

呼出例：

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"

応答例：

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

SSHキーの追加

既存の認証情報のセットに SSHキーを追加します。

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

パラメータ

名称 タイプ 概要
SshPublicKeyBody string ssh-rsaのように文字列の先頭に暗号化の種類に関する情報を含むSSH公開鍵。

呼出例：

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

応答例：

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

SSHキーの削除

認証情報のセットから既存のSSHキーを削除します。

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

呼出例：

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"

応答例：

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