API documentation

TLDR - Quick Summary

What: Use REST API to manage SFTP Gateway programmatically

Auth: POST web admin credentials (plus the client-id/secret from /opt/sftpgw/application.properties) to https://<host>/backend/login to get a Bearer token

Endpoints: /3.0.0/cloudconnections, /3.0.0/folders, /3.0.0/users with the Bearer token (creating users needs an active license with SFTP user capacity)

API Reference: https://thorntech-public-documents.s3.amazonaws.com/sftpgateway/KB/openapi.json (SFTP Gateway 3.10.0, OpenAPI 3.1). Import it into https://editor.swagger.io with File > Import File

Overview

This article covers how to use the REST API of SFTP Gateway. By the end of this article, you should be able to create an SFTP user. This article also covers the prerequisite steps needed along the way, such as creating a Cloud Connection.

This is the overall process:

• Download the API reference (OpenAPI format) and view it in Swagger Editor
• Get the application client-id and client-secret
• Use the credentials of both the application and web admin user to get an access token
• Using the access token, create a Cloud Connection
• Using the access token, create a Folder
• Using the access token, create an SFTP user

The examples use curl. If you prefer Postman, enter the same URL, method, headers and body in a Postman request.

Before you get started

The API requires the credentials of a web admin user in order to obtain an access token.

If you haven't already done so, take a moment to go through the First Launch Experience to create a web admin user.

You can also create a web admin user via the API, using the admin/config endpoint.

Note: No credentials are needed to call the /admin/config endpoint. However, this endpoint is disabled as soon as the first web admin user is created.

View the API reference

The SFTP Gateway API reference describes every endpoint of SFTP Gateway 3.10.0 in OpenAPI 3.1 format:

https://thorntech-public-documents.s3.amazonaws.com/sftpgateway/KB/openapi.json

To browse it:

1. Download the file, for example with curl -O https://thorntech-public-documents.s3.amazonaws.com/sftpgateway/KB/openapi.json

2. Go to https://editor.swagger.io

3. Click File > Import File and select the downloaded openapi.json

The right side of the editor shows the endpoints grouped by area, with the request and response format of each one. Enter your VM's hostname or IP address in the host server variable to see the full URLs.

All endpoint paths are relative to https://<ip-address>/backend. For example, the /3.0.0/users endpoint is at https://<ip-address>/backend/3.0.0/users.

1. Get the access token

Before you make any API calls, you need an access token for a web admin user. This token needs to be included in the header of each API call to authorize your access.

To get an access token, you need to gather four pieces of information:

• Application credentials
  • client-id
  • client-secret
• Web admin user credentials
  • username
  • password

You supply this information to the /login endpoint. In return, you will receive a Bearer token which acts as your credentials for all subsequent API calls.

1a. Gather the application client-id and client-secret

The application credentials are located in Java's application.properties file.

SSH into your VM, and show the contents of this file:

sudo su
cat /opt/sftpgw/application.properties

Your output should look like this:

Copy the values of the following properties:

• security.client-id
• security.client-secret

1b. Retrieve the access token

Send a POST request to the /login endpoint. Use the application credentials for HTTP Basic authentication, and send the web admin credentials as form data:

curl -k -u '<client-id>:<client-secret>' \
  -F grant_type=password \
  -F username='<admin-username>' \
  -F password='<admin-password>' \
  -F scope=read \
  https://<ip-address>/backend/login

• grant_type: The literal string password
• username: The username of the web admin user
• password: The password of the web admin user
• scope: The literal string read

The response contains the token in access_token, along with token_type (Bearer) and expires_in, the number of seconds until the token expires (about 8 hours).

To keep the token in a shell variable for the next steps, pipe the response through jq:

TOKEN=$(curl -s -k -u '<client-id>:<client-secret>' \
  -F grant_type=password -F username='<admin-username>' -F password='<admin-password>' -F scope=read \
  https://<ip-address>/backend/login | jq -r .access_token)

Note: The -k option skips certificate verification for the self-signed certificate that SFTP Gateway uses by default. Leave it out if your VM has a trusted certificate.

2. Create underlying resources

Before you create an SFTP user, you need to first create a Cloud Connection and a Folder. The SFTP user's Home Directory will point to the Folder that you create.

2a. Create a Cloud Connection

This example authenticates with a service account JSON key. The API expects the key file's contents base64-encoded in jwtToken. Encode it on your own machine:

# Linux
base64 -w0 my-service-account-key.json
# macOS
base64 -i my-service-account-key.json

Then send a POST request to /3.0.0/cloudconnections with the access token and a JSON body:

curl -k -X POST https://<ip-address>/backend/3.0.0/cloudconnections \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "API-Test",
        "cloudProvider": "gcp",
        "basePrefix": "gs://winterwonderland/",
        "jwtToken": "<base64-encoded-key-file>",
        "jsonKeyFilename": "my-service-account-key.json",
        "useInstanceCredentials": false
      }'

• name: This is the name of the Cloud Connection
• cloudProvider: Set this to gcp
• basePrefix: Use the Bucket URL. In this example, gs://winterwonderland/ is the Bucket URL
• jwtToken: The base64-encoded contents of your service account's JSON key file
• jsonKeyFilename: The name of that JSON key file
• useInstanceCredentials: Set this to false

Note: The JSON key file is a credential. Encode it locally as shown above rather than uploading it to an online encoding website.

In the response, you will get the id of the Cloud Connection. You will use this value in the next section.

Note: If the VM has no default storage yet, the first Cloud Connection you create becomes the default storage location.

2b. Create a Folder

Now that the Cloud Connection has been created, create a folder that points to it:

curl -k -X POST https://<ip-address>/backend/3.0.0/folders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "api-test", "cloudConnectionId": 1}'

• name: This is the name of the Folder
• cloudConnectionId: Use the Cloud Connection id from the previous step

In the response, you will get the id of the Folder. You will use this value in the next section.

3. Create an SFTP User

Now that you have a Folder that points to a Cloud Connection, you can create an SFTP user:

curl -k -X POST https://<ip-address>/backend/3.0.0/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "homeFolderId": 2, "username": "user1", "password": "<sftp-user-password>"}'

• enabled: Set this to true
• homeFolderId: Use the Folder id you obtained from the previous step
• username: The username of the SFTP user
• password: The password of the SFTP user. It must meet the password policy, which the /3.0.0/password/policy endpoint returns

Creating SFTP users requires an active license with SFTP user capacity. Without one, the API responds with a message such as Your license is restricted to 0 users.

You should now be able to use your newly created SFTP user to log in via SFTP.