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 header as such:
Authorization: Bearer ${SFTPTOGO_API_KEY}

API 키는 SFTPTOGO_API_KEY 환경 변수로서 Heroku 애플리케이션에서 제공됩니다.

아래 문서에서는 다음 변수가 설정되어 있다고 가정하고 작성해 보겠습니다:

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
Parameters:

명칭 종류 설명
Alias string 인증정보의 이름 (로그인으로는 사용불가)
UserName string 서버에 연결할 때 이 인증정보의 사용자 이름입니다. 영숫자, 밑줄, 하이픈 또는 마침표가 포함된 최소 10자에서 최대 100자까지 입력해야 합니다.
Password string 서버에 연결할 때 이 인증정보의 패스워드입니다. 조직 수준의 패스워드 정책을 준수해야 합니다.
HomeDirectory string 사용자의 홈 디렉토리 - 클라이언트가 명시적으로 달리 정의하지 않은 경우 이 디렉토리가 사용자의 기본 디렉터리입니다.
ChrootDirectory string 설정하면 사용자는 이 디렉터리에 바인딩되며 상위 또는 형제 디렉터리에 액세스할 수 없습니다.
Permission string none - 액세스 불가
read-only - 읽기는 가능하나 쓸 수 없음.
read-write - 읽고 쓰기 모두 가능.
write-only - 쓸 수 있으나 읽을 수 없음.
full - 홈디렉토리를 액세스하고 읽고 쓰기가 모두 가능.
State string active(유효) / inactive(무효)

호출 예시:

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

인증정보 업데이트하기

데이터 인수 내에 업데이트에 필요한 키만 전달하여 기존 인증정보를 업데이트합니다.
PATCH https://api.sftptogo.com/organizations/$SFTPTOGO_ORGANIZATION_ID/users/$CREDENTIAL_ID

Parameters - 인증정보 작성하기의 parameters를 확인

호출 예시:

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

Parameters:

명칭 종류 설명
Settings.Network.InboundRules array 이러한 인증정보를 사용하여 서버에 연결할 수 있는 외부 IP를 제어하기 위한 네트워크 인바운드 규칙 모음입니다.
Settings.Network.InboundRules[].Id string 나중에 규칙을 식별하는 데 사용할 수 있는 인바운드 규칙의 고유 식별자입니다.
Settings.Network.InboundRules[].Protocol string * / SFTP / FTPS
Settings.Network.InboundRules[].State string enabled(유효) / disabled(무효)
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
}

패스워드 회전하기

지정된 인증정보의 패스워드를 회전합니다. 열려 있는 세션은 패스워드 로테이션(회전)의 영향을 받지 않습니다. 새 패스워드를 얻으려면 회전 후 패스워드 가져오기 요청을 합니다.
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

Parameters:

명칭 종류 설명
SshPublicKeyBody string 다음과 같이 문자열의 시작 부분에 암호화 유형에 대한 정보가 포함된 SSH 공개 키입니다: ssh-rsa.

호출 예시:

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