sftpgo-mirror/httpd/schema/openapi.yaml

2456 lines
82 KiB
YAML
Raw Normal View History

openapi: 3.0.3
tags:
- name: healthcheck
- name: token
- name: maintenance
- name: admins
- name: connections
- name: defender
- name: quota
- name: folders
- name: users
- name: users API
2019-07-20 10:26:52 +00:00
info:
title: SFTPGo
2021-05-20 16:16:27 +00:00
description: |
SFTPGo allows to securely share your files over SFTP and optionally FTP/S and WebDAV too.
Several storage backends are supported and they are configurable per user, so you can serve a local directory for a user and an S3 bucket (or part of it) for another one.
SFTPGo also supports virtual folders, a virtual folder can use any of the supported storage backends. So you can have, for example, an S3 user that exposes a GCS bucket (or part of it) on a specified path and an encrypted local filesystem on another one.
Virtual folders can be private or shared among multiple users, for shared virtual folders you can define different quota limits for each user.
version: 2.0.9
contact:
name: API support
url: 'https://github.com/drakkan/sftpgo'
license:
name: AGPLv3
url: 'https://www.gnu.org/licenses/agpl-3.0.en.html'
2019-07-20 10:26:52 +00:00
servers:
- url: /api/v2
security:
- BearerAuth: []
2019-07-20 10:26:52 +00:00
paths:
2020-11-01 09:39:10 +00:00
/healthz:
get:
security: []
2020-11-01 09:39:10 +00:00
servers:
- url: /
2020-11-01 09:39:10 +00:00
tags:
- healthcheck
summary: health check
description: This endpoint can be used to check if the application is running and responding to requests
operationId: healthz
2020-11-01 09:39:10 +00:00
responses:
'200':
2020-11-01 09:39:10 +00:00
description: successful operation
content:
text/plain:
schema:
type: string
example: ok
/token:
get:
security:
- BasicAuth: []
tags:
- token
summary: Get a new admin access token
description: Returns an access token and its expiration
operationId: get_token
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Token'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/logout:
get:
tags:
- token
summary: Invalidate an admin access token
description: Allows to invalidate an admin token before its expiration
operationId: logout
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/user/token:
get:
security:
- BasicAuth: []
tags:
- token
summary: Get a new user access token
description: Returns an access token and its expiration
operationId: get_user_token
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Token'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/user/logout:
get:
tags:
- token
summary: Invalidate a user access token
description: Allows to invalidate a client token before its expiration
operationId: client_logout
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
2019-08-08 08:01:33 +00:00
/version:
get:
tags:
- maintenance
2019-08-08 08:01:33 +00:00
summary: Get version details
description: 'Returns version details such as the version number, build date, commit hash and enabled features'
2019-08-08 08:01:33 +00:00
operationId: get_version
responses:
'200':
2019-08-08 08:01:33 +00:00
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/VersionInfo'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/changepwd/admin:
put:
tags:
- admins
summary: Change admin password
description: Changes the password for the logged in admin. Please use /admin/changepwd instead
operationId: change_admin_pwd
deprecated: true
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PwdChange'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/admin/changepwd:
put:
tags:
- admins
summary: Change admin password
description: Changes the password for the logged in admin
operationId: change_admin_password
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PwdChange'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/connections:
2019-07-20 10:26:52 +00:00
get:
tags:
2020-11-01 09:39:10 +00:00
- connections
summary: Get connections details
description: Returns the active users and info about their current uploads/downloads
operationId: get_connections
2019-07-20 10:26:52 +00:00
responses:
'200':
2019-07-20 10:26:52 +00:00
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ConnectionStatus'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
'/connections/{connectionID}':
2019-07-20 10:26:52 +00:00
delete:
tags:
2020-11-01 09:39:10 +00:00
- connections
summary: Close connection
description: Terminates an active connection
operationId: close_connection
parameters:
2020-11-01 09:39:10 +00:00
- name: connectionID
in: path
description: ID of the connection to close
required: true
schema:
type: string
2019-07-20 10:26:52 +00:00
responses:
'200':
2019-07-20 10:26:52 +00:00
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
message: Connection closed
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/defender/bantime:
2021-01-02 18:33:24 +00:00
get:
tags:
- defender
summary: Get ban time
description: Returns the ban time for the specified IPv4/IPv6 address
2021-01-02 18:33:24 +00:00
operationId: get_ban_time
parameters:
- in: query
name: ip
required: true
description: IPv4/IPv6 address
schema:
type: string
responses:
'200':
2021-01-02 18:33:24 +00:00
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/BanStatus'
'401':
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/Unauthorized'
'403':
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/Forbidden'
'404':
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/NotFound'
'500':
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/defender/unban:
post:
tags:
- defender
summary: Unban
description: Removes the specified IPv4/IPv6 from the banned ones
2021-01-02 18:33:24 +00:00
operationId: unban_host
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
ip:
type: string
description: IPv4/IPv6 address to remove
responses:
'200':
2021-01-02 18:33:24 +00:00
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
'400':
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/BadRequest'
'401':
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/Unauthorized'
'403':
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/Forbidden'
'404':
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/NotFound'
'500':
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/defender/score:
get:
tags:
- defender
summary: Get score
description: Returns the score for the specified IPv4/IPv6 address
2021-01-02 18:33:24 +00:00
operationId: get_score
parameters:
- in: query
name: ip
required: true
description: IPv4/IPv6 address
schema:
type: string
responses:
'200':
2021-01-02 18:33:24 +00:00
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ScoreStatus'
'401':
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/Unauthorized'
'403':
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/Forbidden'
'404':
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/NotFound'
'500':
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/quota-scans:
2019-07-20 10:26:52 +00:00
get:
tags:
2020-11-01 09:39:10 +00:00
- quota
summary: Get quota scans
description: Returns active user quota scans
operationId: get_quota_scans
2019-07-20 10:26:52 +00:00
responses:
'200':
2019-07-20 10:26:52 +00:00
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/QuotaScan'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
2019-07-20 10:26:52 +00:00
post:
tags:
2020-11-01 09:39:10 +00:00
- quota
summary: Start user quota scan
description: Starts a new quota scan for the given user. A quota scan updates the number of files and their total size for the specified user and the virtual folders, if any, included in his quota
2019-07-20 10:26:52 +00:00
operationId: start_quota_scan
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/User'
2019-07-20 10:26:52 +00:00
responses:
'202':
2019-07-20 10:26:52 +00:00
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
message: Scan started
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/quota-update:
put:
tags:
2020-11-01 09:39:10 +00:00
- quota
summary: Update user quota limits
description: Sets the current used quota limits for the given user
operationId: quota_update
parameters:
- in: query
name: mode
required: false
description: the update mode specifies if the given quota usage values should be added or replace the current ones
schema:
type: string
enum:
- add
- reset
description: |
Update type:
* `add` - add the specified quota limits to the current used ones
* `reset` - reset the values to the specified ones. This is the default
example: reset
requestBody:
required: true
description: 'The only user mandatory fields are username, used_quota_size and used_quota_files. Please note that if the quota fields are missing they will default to 0, this means that if mode is "add" the current value will remain unchanged, if mode is "reset" the missing field is set to 0'
content:
application/json:
schema:
$ref: '#/components/schemas/User'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
message: Quota updated
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/folder-quota-update:
put:
tags:
2020-11-01 09:39:10 +00:00
- quota
summary: Update folder quota limits
description: Sets the current used quota limits for the given folder
operationId: folder_quota_update
parameters:
- in: query
name: mode
required: false
description: the update mode specifies if the given quota usage values should be added or replace the current ones
schema:
type: string
enum:
- add
- reset
description: |
Update type:
* `add` - add the specified quota limits to the current used ones
* `reset` - reset the values to the specified ones. This is the default
example: reset
requestBody:
required: true
description: 'The only folder mandatory fields are mapped_path,used_quota_size and used_quota_files. Please note that if the used quota fields are missing they will default to 0, this means that if mode is "add" the current value will remain unchanged, if mode is "reset" the missing field is set to 0'
content:
application/json:
schema:
$ref: '#/components/schemas/BaseVirtualFolder'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
message: Quota updated
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/folder-quota-scans:
get:
tags:
2020-11-01 09:39:10 +00:00
- quota
summary: Get folders quota scans
description: Returns the active quota scans for folders
operationId: get_folders_quota_scans
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FolderQuotaScan'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
post:
tags:
2020-11-01 09:39:10 +00:00
- quota
summary: Start folder quota scan
description: Starts a new quota scan for the given folder. A quota scan update the number of files and their total size for the specified folder
operationId: start_folder_quota_scan
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BaseVirtualFolder'
responses:
'202':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
message: Scan started
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/folders:
get:
tags:
2020-11-01 09:39:10 +00:00
- folders
summary: Get folders
description: Returns an array with one or more folders
operationId: get_folders
parameters:
- in: query
name: offset
schema:
type: integer
minimum: 0
default: 0
required: false
- in: query
name: limit
schema:
type: integer
minimum: 1
maximum: 500
default: 100
required: false
description: 'The maximum number of items to return. Max value is 500, default is 100'
- in: query
name: order
required: false
description: Ordering folders by path. Default ASC
schema:
type: string
enum:
- ASC
- DESC
example: ASC
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BaseVirtualFolder'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
post:
tags:
2020-11-01 09:39:10 +00:00
- folders
summary: Add folder
operationId: add_folder
description: Adds a new folder. A quota scan is required to update the used files/size
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BaseVirtualFolder'
responses:
'201':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/BaseVirtualFolder'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
'/folders/{name}':
parameters:
- name: name
in: path
description: folder name
required: true
schema:
type: string
get:
tags:
- folders
summary: Find folders by name
description: Returns the folder with the given name if it exists.
operationId: get_folder_by_name
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/BaseVirtualFolder'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
put:
tags:
- folders
summary: Update folder
description: Updates an existing folder
operationId: update_folder
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BaseVirtualFolder'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
message: User updated
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
delete:
tags:
2020-11-01 09:39:10 +00:00
- folders
summary: Delete folder
description: Deletes an existing folder
operationId: delete_folder
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
message: User deleted
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/admins:
2019-07-20 10:26:52 +00:00
get:
tags:
- admins
summary: Get admins
description: Returns an array with one or more admins. For security reasons hashed passwords are omitted in the response
operationId: get_admins
2019-07-20 10:26:52 +00:00
parameters:
- in: query
name: offset
schema:
type: integer
minimum: 0
default: 0
required: false
- in: query
name: limit
schema:
type: integer
minimum: 1
maximum: 500
default: 100
required: false
description: 'The maximum number of items to return. Max value is 500, default is 100'
2019-07-20 10:26:52 +00:00
- in: query
name: order
required: false
description: Ordering admins by username. Default ASC
2019-07-20 10:26:52 +00:00
schema:
type: string
enum:
- ASC
- DESC
example: ASC
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Admin'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
post:
tags:
- admins
summary: Add admin
description: Adds a new admin
operationId: add_admin
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Admin'
examples:
example-1:
value:
id: 1
status: 0
username: string
description: string
password: pa$$word
email: user@example.com
permissions:
- '*'
filters:
allow_list:
- 192.0.2.0/24
- '2001:db8::/32'
additional_info: string
responses:
'201':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Admin'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
'/admins/{username}':
parameters:
- name: username
in: path
description: the admin username
required: true
schema:
type: string
get:
tags:
- admins
summary: Find admins by username
description: Returns the admin with the given username, if it exists. For security reasons the hashed password is omitted in the response
operationId: get_admin_by_username
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Admin'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
put:
tags:
- admins
summary: Update admin
description: Updates an existing admin
operationId: update_admin
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Admin'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
message: Admin updated
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
delete:
tags:
- admins
summary: Delete admin
description: Deletes an existing admin
operationId: delete_admin
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
message: Admin deleted
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/users:
get:
tags:
- users
summary: Get users
description: Returns an array with one or more users. For security reasons hashed passwords are omitted in the response
operationId: get_users
parameters:
- in: query
name: offset
schema:
type: integer
minimum: 0
default: 0
required: false
- in: query
name: limit
schema:
type: integer
minimum: 1
maximum: 500
default: 100
required: false
description: 'The maximum number of items to return. Max value is 500, default is 100'
2019-07-20 10:26:52 +00:00
- in: query
name: order
2019-07-20 10:26:52 +00:00
required: false
description: Ordering users by username. Default ASC
2019-07-20 10:26:52 +00:00
schema:
type: string
enum:
- ASC
- DESC
example: ASC
2019-07-20 10:26:52 +00:00
responses:
'200':
2019-07-20 10:26:52 +00:00
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
2019-07-20 10:26:52 +00:00
post:
tags:
2020-11-01 09:39:10 +00:00
- users
summary: Add user
description: Adds a new user
2019-07-20 10:26:52 +00:00
operationId: add_user
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/User'
2019-07-20 10:26:52 +00:00
responses:
'201':
2019-07-20 10:26:52 +00:00
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
'/users/{username}':
parameters:
- name: username
in: path
description: the username
required: true
schema:
type: string
2019-07-20 10:26:52 +00:00
get:
tags:
2020-11-01 09:39:10 +00:00
- users
summary: Find users by username
description: Returns the user with the given username if it exists. For security reasons the hashed password is omitted in the response
operationId: get_user_by_username
2019-07-20 10:26:52 +00:00
responses:
'200':
2019-07-20 10:26:52 +00:00
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
2019-07-20 10:26:52 +00:00
put:
tags:
2020-11-01 09:39:10 +00:00
- users
summary: Update user
description: 'Updates an existing user and optionally disconnects it, if connected, to apply the new settings'
operationId: update_user
parameters:
2020-11-01 09:39:10 +00:00
- in: query
name: disconnect
schema:
type: integer
enum:
- 0
- 1
description: |
2020-11-01 09:39:10 +00:00
Disconnect:
* `0` The user will not be disconnected and it will continue to use the old configuration until connected. This is the default
* `1` The user will be disconnected after a successful update. It must login again and so it will be forced to use the new configuration
2019-07-20 10:26:52 +00:00
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/User'
2019-07-20 10:26:52 +00:00
responses:
'200':
2019-07-20 10:26:52 +00:00
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
message: User updated
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
2019-07-20 10:26:52 +00:00
delete:
tags:
2020-11-01 09:39:10 +00:00
- users
summary: Delete user
description: Deletes an existing user
operationId: delete_user
2019-07-20 10:26:52 +00:00
responses:
'200':
2019-07-20 10:26:52 +00:00
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
message: User deleted
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/status:
get:
tags:
- maintenance
summary: Get status
description: Retrieves the status of the active services
operationId: get_status
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ServicesStatus'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
2019-12-27 22:12:44 +00:00
/dumpdata:
get:
tags:
2020-11-01 09:39:10 +00:00
- maintenance
summary: Dump data
description: 'Backups data as data provider independent JSON. The backup can be saved in a local file on the server, to avoid exposing sensitive data over the network, or returned as response body. The output of dumpdata can be used as input for loaddata'
2019-12-27 22:12:44 +00:00
operationId: dumpdata
parameters:
- in: query
2021-01-22 18:42:18 +00:00
name: output-file
2019-12-27 22:12:44 +00:00
schema:
type: string
2021-01-22 18:42:18 +00:00
description: Path for the file to write the JSON serialized data to. This path is relative to the configured "backups_path". If this file already exists it will be overwritten. To return the backup as response body set `output_data` to true instead.
- in: query
name: output-data
schema:
type: integer
enum:
- 0
- 1
description: |
output data:
2021-01-22 18:42:18 +00:00
* `0` or any other value != 1, the backup will be saved to a file on the server, `output_file` is required
* `1` the backup will be returned as response body
- in: query
name: indent
schema:
type: integer
enum:
- 0
- 1
description: |
indent:
* `0` no indentation. This is the default
* `1` format the output JSON
2019-12-27 22:12:44 +00:00
responses:
'200':
2019-12-27 22:12:44 +00:00
description: successful operation
content:
application/json:
schema:
2021-01-22 18:42:18 +00:00
oneOf:
- $ref: '#/components/schemas/ApiResponse'
- $ref: '#/components/schemas/BackupData'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
2019-12-27 22:12:44 +00:00
/loaddata:
2021-01-22 18:42:18 +00:00
parameters:
- in: query
name: scan-quota
schema:
type: integer
enum:
- 0
- 1
- 2
description: |
2021-01-22 18:42:18 +00:00
Quota scan:
* `0` no quota scan is done, the imported users/folders will have used_quota_size and used_quota_files = 0 or the existing values if they already exists. This is the default
* `1` scan quota
* `2` scan quota if the user has quota restrictions
required: false
- in: query
name: mode
schema:
type: integer
enum:
- 0
- 1
- 2
description: |
2021-01-22 18:42:18 +00:00
Mode:
* `0` New users/admins are added, existing users/admins are updated. This is the default
* `1` New users/admins are added, existing users/admins are not modified
* `2` New users are added, existing users are updated and, if connected, they are disconnected and so forced to use the new configuration
2019-12-27 22:12:44 +00:00
get:
tags:
2020-11-01 09:39:10 +00:00
- maintenance
summary: Load data from path
description: 'Restores SFTPGo data from a JSON backup file on the server. Users, folders and admins will be restored one by one and the restore is stopped if a user/folder/admin cannot be added or updated, so it could happen a partial restore'
2021-01-22 18:42:18 +00:00
operationId: loaddata_from_file
2019-12-27 22:12:44 +00:00
parameters:
- in: query
2021-01-22 18:42:18 +00:00
name: input-file
2019-12-27 22:12:44 +00:00
schema:
type: string
required: true
description: Path for the file to read the JSON serialized data from. This can be an absolute path or a path relative to the configured "backups_path". The max allowed file size is 10MB
2021-01-22 18:42:18 +00:00
responses:
'200':
2021-01-22 18:42:18 +00:00
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
2021-01-22 18:42:18 +00:00
example:
message: Data restored
'400':
2021-01-22 18:42:18 +00:00
$ref: '#/components/responses/BadRequest'
'401':
2021-01-22 18:42:18 +00:00
$ref: '#/components/responses/Unauthorized'
'403':
2021-01-22 18:42:18 +00:00
$ref: '#/components/responses/Forbidden'
'500':
2021-01-22 18:42:18 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
post:
tags:
- maintenance
summary: Load data
description: 'Restores SFTPGo data from a JSON backup. Users, folders and admins will be restored one by one and the restore is stopped if a user/folder/admin cannot be added or updated, so it could happen a partial restore'
2021-01-22 18:42:18 +00:00
operationId: loaddata_from_request_body
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BackupData'
2019-12-27 22:12:44 +00:00
responses:
'200':
2019-12-27 22:12:44 +00:00
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
2019-12-27 22:12:44 +00:00
example:
message: Data restored
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/user/changepwd:
put:
tags:
- users API
summary: Change user password
description: Changes the password for the logged in user
operationId: change_user_password
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PwdChange'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/user/publickeys:
get:
tags:
- users API
summary: Get the user's public keys
description: Returns the public keys for the logged in user
operationId: get_user_public_keys
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
type: string
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
put:
tags:
- users API
summary: Set the user's public keys
description: Sets the public keys for the logged in user. Public keys must be in OpenSSH format
operationId: set_user_public_keys
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
type: string
description: Public key in OpenSSH format
example: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPVILdH2u3yV5SAeE6XksD1z1vXRg0E4hJUov8ITDAZ2 user@host
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/user/folder:
get:
tags:
- users API
summary: Read folders contents
description: Returns the contents of the specified folder for the logged in user
operationId: get_user_folder_contents
parameters:
- in: query
name: path
description: Path to the folder to read. It must be URL encoded, for example the path "my dir/àdir" must be sent as "my%20dir%2F%C3%A0dir". If empty or missing the root folder is assumed
schema:
type: string
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DirEntry'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/user/file:
get:
tags:
- users API
summary: Download a single file
description: Returns the file contents as response body
operationId: get_user_file
parameters:
- in: query
name: path
required: true
description: Path to the file to download. It must be URL encoded, for example the path "my dir/àdir/file.txt" must be sent as "my%20dir%2F%C3%A0dir%2Ffile.txt"
schema:
type: string
responses:
'200':
description: successful operation
content:
'*/*':
schema:
type: string
format: binary
'206':
description: successful operation
content:
'*/*':
schema:
type: string
format: binary
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/user/streamzip:
post:
tags:
- users API
summary: Download multiple files and folders as a single zip file
description: A zip file, containing the specified files and folders, will be generated on the fly and returned as response body. Only folders and regular files will be included in the zip
operationId: streamzip
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
type: string
description: Absolute file or folder path
responses:
'200':
description: successful operation
content:
'application/zip':
schema:
type: string
format: binary
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
2019-07-20 10:26:52 +00:00
components:
responses:
BadRequest:
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
Forbidden:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
NotFound:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
Conflict:
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
InternalServerError:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
DefaultResponse:
description: Unexpected Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
2019-07-20 10:26:52 +00:00
schemas:
Permission:
type: string
enum:
- '*'
- list
- download
- upload
- overwrite
2019-07-20 10:26:52 +00:00
- delete
- rename
- create_dirs
- create_symlinks
- chmod
- chown
- chtimes
description: |
2019-07-20 10:26:52 +00:00
Permissions:
2019-09-18 20:19:34 +00:00
* `*` - all permissions are granted
2019-07-20 10:26:52 +00:00
* `list` - list items is allowed
* `download` - download files is allowed
* `upload` - upload files is allowed
* `overwrite` - overwrite an existing file, while uploading, is allowed. upload permission is required to allow file overwrite
2019-07-20 10:26:52 +00:00
* `delete` - delete files or directories is allowed
* `rename` - rename files or directories is allowed
* `create_dirs` - create directories is allowed
* `create_symlinks` - create links is allowed
* `chmod` changing file or directory permissions is allowed
* `chown` changing file or directory owner and group is allowed
* `chtimes` changing file or directory access and modification time is allowed
DirPermissions:
type: object
additionalProperties:
type: array
items:
$ref: '#/components/schemas/Permission'
minItems: 1
minProperties: 1
description: 'hash map with directory as key and an array of permissions as value. Directories must be absolute paths, permissions for root directory ("/") are required'
AdminPermissions:
type: string
enum:
- '*'
- add_users
- edit_users
- del_users
- view_users
- view_conns
- close_conns
- view_status
- manage_admins
- quota_scans
- manage_system
- manage_defender
- view_defender
description: |
Admin permissions:
* `*` - all permissions are granted
* `add_users` - add new users is allowed
* `edit_users` - change existing users is allowed
* `del_users` - remove users is allowed
* `view_users` - list users is allowed
* `view_conns` - list active connections is allowed
* `close_conns` - close active connections is allowed
* `view_status` - view the server status is allowed
* `manage_admins` - manage other admins is allowed
* `manage_defender` - remove ip from the dynamic blocklist is allowed
* `view_defender` - list the dynamic blocklist is allowed
LoginMethods:
type: string
enum:
- publickey
- password
- keyboard-interactive
- publickey+password
- publickey+keyboard-interactive
- TLSCertificate
- TLSCertificate+password
description: |
Available login methods. To enable multi-step authentication you have to allow only multi-step login methods
* `publickey`
* `password`
* `keyboard-interactive`
* `publickey+password` - multi-step auth: public key and password
* `publickey+keyboard-interactive` - multi-step auth: public key and keyboard interactive
* `TLSCertificate`
* `TLSCertificate+password` - multi-step auth: TLS client certificate and password
SupportedProtocols:
type: string
enum:
- SSH
- FTP
- DAV
- HTTP
description: |
Protocols:
* `SSH` - includes both SFTP and SSH commands
* `FTP` - plain FTP and FTPES/FTPS
* `DAV` - WebDAV over HTTP/HTTPS
* `HTTP` - WebClient
WebClientOptions:
type: string
enum:
- publickey-change-disabled
description: |
Options:
* `publickey-change-disabled` - changing SSH public keys is not allowed
PatternsFilter:
type: object
properties:
path:
type: string
description: 'exposed virtual path, if no other specific filter is defined, the filter apply for sub directories too. For example if filters are defined for the paths "/" and "/sub" then the filters for "/" are applied for any file outside the "/sub" directory'
allowed_patterns:
type: array
items:
type: string
description: 'list of, case insensitive, allowed shell like file patterns.'
example:
- '*.jpg'
- a*b?.png
denied_patterns:
type: array
items:
type: string
description: 'list of, case insensitive, denied shell like file patterns. Denied patterns are evaluated before the allowed ones'
example:
- '*.zip'
HooksFilter:
type: object
properties:
external_auth_disabled:
type: boolean
example: false
description: If true, the external auth hook, if defined, will not be executed
pre_login_disabled:
type: boolean
example: false
description: If true, the pre-login hook, if defined, will not be executed
check_password_disabled:
type: boolean
example: false
description: If true, the check password hook, if defined, will not be executed
description: User specific hook overrides
UserFilters:
type: object
properties:
allowed_ip:
type: array
items:
type: string
description: 'only clients connecting from these IP/Mask are allowed. IP/Mask must be in CIDR notation as defined in RFC 4632 and RFC 4291, for example "192.0.2.0/24" or "2001:db8::/32"'
example:
- 192.0.2.0/24
- '2001:db8::/32'
denied_ip:
type: array
items:
type: string
description: clients connecting from these IP/Mask are not allowed. Denied rules are evaluated before allowed ones
example:
- 172.16.0.0/16
denied_login_methods:
type: array
items:
$ref: '#/components/schemas/LoginMethods'
description: if null or empty any available login method is allowed
denied_protocols:
type: array
items:
$ref: '#/components/schemas/SupportedProtocols'
description: if null or empty any available protocol is allowed
file_patterns:
type: array
items:
$ref: '#/components/schemas/PatternsFilter'
description: 'filters based on shell like file patterns. These restrictions do not apply to files listing for performance reasons, so a denied file cannot be downloaded/overwritten/renamed but it will still be in the list of files. Please note that these restrictions can be easily bypassed'
max_upload_file_size:
type: integer
format: int64
description: 'maximum allowed size, as bytes, for a single file upload. The upload will be aborted if/when the size of the file being sent exceeds this limit. 0 means unlimited. This restriction does not apply for SSH system commands such as `git` and `rsync`'
tls_username:
type: string
enum:
- None
- CommonName
description: 'defines the TLS certificate field to use as username. For FTP clients it must match the name provided using the "USER" command. For WebDAV, if no username is provided, the CN will be used as username. For WebDAV clients it must match the implicit or provided username. Ignored if mutual TLS is disabled'
hooks:
$ref: '#/components/schemas/HooksFilter'
disable_fs_checks:
type: boolean
example: false
description: Disable checks for existence and automatic creation of home directory and virtual folders. SFTPGo requires that the user's home directory, virtual folder root, and intermediate paths to virtual folders exist to work properly. If you already know that the required directories exist, disabling these checks will speed up login. You could, for example, disable these checks after the first login
web_client:
type: array
items:
$ref: '#/components/schemas/WebClientOptions'
description: WebClient related configuration options
description: Additional user options
Secret:
type: object
properties:
status:
type: string
enum:
- Plain
- AES-256-GCM
2020-11-30 20:46:34 +00:00
- Secretbox
- GCP
- AWS
- VaultTransit
- Redacted
description: 'Set to "Plain" to add or update an existing secret, set to "Redacted" to preserve the existing value'
payload:
type: string
key:
type: string
additional_data:
type: string
mode:
type: integer
description: 1 means encrypted using a master key
description: The secret is encrypted before saving, so to set a new secret you must provide a payload and set the status to "Plain". The encryption key and additional data will be generated automatically. If you set the status to "Redacted" the existig secret will be preserved
S3Config:
type: object
properties:
bucket:
type: string
minLength: 1
region:
type: string
minLength: 1
access_key:
type: string
access_secret:
$ref: '#/components/schemas/Secret'
endpoint:
type: string
description: optional endpoint
storage_class:
type: string
upload_part_size:
type: integer
description: 'the buffer size (in MB) to use for multipart uploads. The minimum allowed part size is 5MB, and if this value is set to zero, the default value (5MB) for the AWS SDK will be used. The minimum allowed value is 5.'
upload_concurrency:
type: integer
description: 'the number of parts to upload in parallel. If this value is set to zero, the default value (2) will be used'
key_prefix:
type: string
description: 'key_prefix is similar to a chroot directory for a local filesystem. If specified the user will only see contents that starts with this prefix and so you can restrict access to a specific virtual folder. The prefix, if not empty, must not start with "/" and must end with "/". If empty the whole bucket contents will be available'
example: folder/subfolder/
description: S3 Compatible Object Storage configuration details
GCSConfig:
type: object
properties:
bucket:
type: string
minLength: 1
credentials:
$ref: '#/components/schemas/Secret'
automatic_credentials:
type: integer
enum:
- 0
- 1
description: |
Automatic credentials:
* `0` - disabled, explicit credentials, using a JSON credentials file, must be provided. This is the default value if the field is null
* `1` - enabled, we try to use the Application Default Credentials (ADC) strategy to find your application's credentials
storage_class:
type: string
key_prefix:
type: string
description: 'key_prefix is similar to a chroot directory for a local filesystem. If specified the user will only see contents that starts with this prefix and so you can restrict access to a specific virtual folder. The prefix, if not empty, must not start with "/" and must end with "/". If empty the whole bucket contents will be available'
example: folder/subfolder/
description: 'Google Cloud Storage configuration details. The "credentials" field must be populated only when adding/updating a user. It will be always omitted, since there are sensitive data, when you search/get users'
2020-10-25 07:18:48 +00:00
AzureBlobFsConfig:
type: object
properties:
container:
type: string
account_name:
type: string
description: 'Storage Account Name, leave blank to use SAS URL'
2020-10-25 07:18:48 +00:00
account_key:
$ref: '#/components/schemas/Secret'
2020-10-25 07:18:48 +00:00
sas_url:
type: string
description: 'Shared access signature URL, leave blank if using account/key'
2020-10-25 07:18:48 +00:00
endpoint:
type: string
description: 'optional endpoint. Default is "blob.core.windows.net". If you use the emulator the endpoint must include the protocol, for example "http://127.0.0.1:10000"'
2020-10-25 07:18:48 +00:00
upload_part_size:
type: integer
description: 'the buffer size (in MB) to use for multipart uploads. If this value is set to zero, the default value (4MB) will be used.'
2020-10-25 07:18:48 +00:00
upload_concurrency:
type: integer
description: 'the number of parts to upload in parallel. If this value is set to zero, the default value (2) will be used'
access_tier:
type: string
enum:
- ''
- Archive
- Hot
- Cool
2020-10-25 07:18:48 +00:00
key_prefix:
type: string
description: 'key_prefix is similar to a chroot directory for a local filesystem. If specified the user will only see contents that starts with this prefix and so you can restrict access to a specific virtual folder. The prefix, if not empty, must not start with "/" and must end with "/". If empty the whole container contents will be available'
2020-10-25 07:18:48 +00:00
example: folder/subfolder/
use_emulator:
type: boolean
description: Azure Blob Storage configuration details
2020-12-05 12:48:13 +00:00
CryptFsConfig:
type: object
properties:
passphrase:
$ref: '#/components/schemas/Secret'
description: Crypt filesystem configuration details
2020-12-12 09:31:09 +00:00
SFTPFsConfig:
type: object
properties:
endpoint:
type: string
description: 'remote SFTP endpoint as host:port'
2020-12-12 09:31:09 +00:00
username:
type: string
description: you can specify a password or private key or both. In the latter case the private key will be tried first.
password:
$ref: '#/components/schemas/Secret'
private_key:
$ref: '#/components/schemas/Secret'
fingerprints:
type: array
items:
type: string
description: 'SHA256 fingerprints to use for host key verification. If you don''t provide any fingerprint the remote host key will not be verified, this is a security risk'
2020-12-12 09:31:09 +00:00
prefix:
type: string
description: Specifying a prefix you can restrict all operations to a given path within the remote SFTP server.
disable_concurrent_reads:
type: boolean
description: Concurrent reads are safe to use and disabling them will degrade performance. Some servers automatically delete files once they are downloaded. Using concurrent reads is problematic with such servers.
buffer_size:
2021-04-03 15:09:08 +00:00
type: integer
minimum: 0
maximum: 16
example: 2
description: The size of the buffer (in MB) to use for transfers. By enabling buffering, the reads and writes, from/to the remote SFTP server, are split in multiple concurrent requests and this allows data to be transferred at a faster rate, over high latency networks, by overlapping round-trip times. With buffering enabled, resuming uploads is not supported and a file cannot be opened for both reading and writing at the same time. 0 means disabled.
FilesystemConfig:
type: object
properties:
provider:
type: integer
enum:
- 0
- 1
- 2
2020-10-25 07:18:48 +00:00
- 3
2020-12-05 12:48:13 +00:00
- 4
2020-12-12 09:31:09 +00:00
- 5
description: |
Providers:
2020-10-25 07:18:48 +00:00
* `0` - Local filesystem
* `1` - S3 Compatible Object Storage
* `2` - Google Cloud Storage
2020-10-25 07:18:48 +00:00
* `3` - Azure Blob Storage
2020-12-05 12:48:13 +00:00
* `4` - Local filesystem encrypted
2020-12-12 09:31:09 +00:00
* `5` - SFTP
s3config:
$ref: '#/components/schemas/S3Config'
gcsconfig:
$ref: '#/components/schemas/GCSConfig'
2020-10-25 07:18:48 +00:00
azblobconfig:
$ref: '#/components/schemas/AzureBlobFsConfig'
2020-12-05 12:48:13 +00:00
cryptconfig:
$ref: '#/components/schemas/CryptFsConfig'
2020-12-12 09:31:09 +00:00
sftpconfig:
$ref: '#/components/schemas/SFTPFsConfig'
description: Storage filesystem details
BaseVirtualFolder:
type: object
properties:
id:
type: integer
format: int32
minimum: 1
name:
type: string
description: unique name for this virtual folder
mapped_path:
type: string
description: absolute filesystem path to use as virtual folder
description:
type: string
description: optional description
used_quota_size:
type: integer
format: int64
used_quota_files:
type: integer
format: int32
last_quota_update:
type: integer
format: int64
description: Last quota update as unix timestamp in milliseconds
users:
type: array
items:
type: string
description: list of usernames associated with this virtual folder
filesystem:
$ref: '#/components/schemas/FilesystemConfig'
description: Defines the filesystem for the virtual folder and the used quota limits. The same folder can be shared among multiple users and each user can have different quota limits or a different virtual path.
VirtualFolder:
allOf:
- $ref: '#/components/schemas/BaseVirtualFolder'
- type: object
properties:
virtual_path:
type: string
quota_size:
type: integer
format: int64
description: 'Quota as size in bytes. 0 menas unlimited, -1 means included in user quota. Please note that quota is updated if files are added/removed via SFTPGo otherwise a quota scan or a manual quota update is needed'
quota_files:
type: integer
format: int32
description: 'Quota as number of files. 0 menas unlimited, , -1 means included in user quota. Please note that quota is updated if files are added/removed via SFTPGo otherwise a quota scan or a manual quota update is needed'
required:
- virtual_path
description: 'A virtual folder is a mapping between a SFTPGo virtual path and a filesystem path outside the user home directory. The specified paths must be absolute and the virtual path cannot be "/", it must be a sub directory. The parent directory for the specified virtual path must exist. SFTPGo will try to automatically create any missing parent directory for the configured virtual folders at user login.'
2019-07-20 10:26:52 +00:00
User:
type: object
properties:
id:
type: integer
format: int32
minimum: 1
status:
type: integer
enum:
- 0
- 1
description: |
status:
* `0` user is disabled, login is not allowed
* `1` user is enabled
2019-07-20 10:26:52 +00:00
username:
type: string
description: username is unique
description:
type: string
description: 'optional description, for example the user full name'
expiration_date:
type: integer
format: int64
description: expiration date as unix timestamp in milliseconds. An expired account cannot login. 0 means no expiration
2019-07-20 10:26:52 +00:00
password:
type: string
format: password
2021-04-25 07:42:19 +00:00
description: password or public key/SSH user certificate are mandatory. If the password has no known hashing algo prefix it will be stored, by default, using bcrypt, argon2id is supported too. You can send a password hashed as bcrypt ($2a$ prefix), argon2id, pbkdf2 or unix crypt and it will be stored as is. For security reasons this field is omitted when you search/get users
public_keys:
type: array
items:
type: string
example: ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEUWwDwEWhTbF0MqAsp/oXK1HR2cElhM8oo1uVmL3ZeDKDiTm4ljMr92wfTgIGDqIoxmVqgYIkAOAhuykAVWBzc= user@host
description: Public keys in OpenSSH format. A password or at least one public key/SSH user certificate are mandatory.
2019-07-20 10:26:52 +00:00
home_dir:
type: string
description: path to the user home directory. The user cannot upload or download files outside this directory. SFTPGo tries to automatically create this folder if missing. Must be an absolute path
virtual_folders:
type: array
items:
$ref: '#/components/schemas/VirtualFolder'
2020-08-11 21:56:10 +00:00
description: mapping between virtual SFTPGo paths and filesystem paths outside the user home directory. Supported for local filesystem only. If one or more of the specified folders are not inside the dataprovider they will be automatically created. You have to create the folder on the filesystem yourself
2019-07-20 10:26:52 +00:00
uid:
type: integer
format: int32
minimum: 0
maximum: 2147483647
description: 'if you run SFTPGo as root user, the created files and directories will be assigned to this uid. 0 means no change, the owner will be the user that runs SFTPGo. Ignored on windows'
2019-07-20 10:26:52 +00:00
gid:
type: integer
format: int32
minimum: 0
maximum: 2147483647
description: 'if you run SFTPGo as root user, the created files and directories will be assigned to this gid. 0 means no change, the group will be the one of the user that runs SFTPGo. Ignored on windows'
2019-07-20 10:26:52 +00:00
max_sessions:
type: integer
format: int32
description: Limit the sessions that a user can open. 0 means unlimited
2019-07-20 10:26:52 +00:00
quota_size:
type: integer
format: int64
2020-08-11 21:56:10 +00:00
description: Quota as size in bytes. 0 menas unlimited. Please note that quota is updated if files are added/removed via SFTPGo otherwise a quota scan or a manual quota update is needed
2019-07-20 10:26:52 +00:00
quota_files:
type: integer
format: int32
2020-08-11 21:56:10 +00:00
description: Quota as number of files. 0 menas unlimited. Please note that quota is updated if files are added/removed via SFTPGo otherwise a quota scan or a manual quota update is needed
2019-07-20 10:26:52 +00:00
permissions:
type: object
2019-07-20 10:26:52 +00:00
items:
$ref: '#/components/schemas/DirPermissions'
2019-07-20 10:26:52 +00:00
minItems: 1
example:
/:
- '*'
/somedir:
- list
- download
2019-07-20 10:26:52 +00:00
used_quota_size:
type: integer
format: int64
used_quota_files:
2019-07-20 10:26:52 +00:00
type: integer
format: int32
last_quota_update:
2019-07-20 10:26:52 +00:00
type: integer
format: int64
description: Last quota update as unix timestamp in milliseconds
2019-07-20 10:26:52 +00:00
upload_bandwidth:
type: integer
format: int32
description: 'Maximum upload bandwidth as KB/s, 0 means unlimited'
2019-07-20 10:26:52 +00:00
download_bandwidth:
type: integer
format: int32
description: 'Maximum download bandwidth as KB/s, 0 means unlimited'
last_login:
type: integer
format: int64
2020-11-30 20:46:34 +00:00
description: Last user login as unix timestamp in milliseconds. It is saved at most once every 10 minutes
filters:
$ref: '#/components/schemas/UserFilters'
filesystem:
$ref: '#/components/schemas/FilesystemConfig'
2020-11-25 21:26:34 +00:00
additional_info:
type: string
description: Free form text field for external systems
AdminFilters:
type: object
properties:
allow_list:
type: array
items:
type: string
description: 'only clients connecting from these IP/Mask are allowed. IP/Mask must be in CIDR notation as defined in RFC 4632 and RFC 4291, for example "192.0.2.0/24" or "2001:db8::/32"'
example:
- 192.0.2.0/24
- '2001:db8::/32'
Admin:
type: object
properties:
id:
type: integer
format: int32
minimum: 1
status:
type: integer
enum:
- 0
- 1
description: |
status:
* `0` user is disabled, login is not allowed
* `1` user is enabled
username:
type: string
description: username is unique
description:
type: string
description: 'optional description, for example the admin full name'
password:
type: string
format: password
description: Admin password. For security reasons this field is omitted when you search/get admins
email:
type: string
format: email
permissions:
type: array
items:
$ref: '#/components/schemas/AdminPermissions'
filters:
$ref: '#/components/schemas/AdminFilters'
additional_info:
type: string
description: Free form text field
Transfer:
2019-07-20 10:26:52 +00:00
type: object
properties:
operation_type:
type: string
enum:
2019-07-20 10:26:52 +00:00
- upload
- download
description: |
Operations:
* `upload`
* `download`
path:
type: string
description: file path for the upload/download
2019-07-20 10:26:52 +00:00
start_time:
type: integer
format: int64
description: start time as unix timestamp in milliseconds
2019-07-20 10:26:52 +00:00
size:
type: integer
format: int64
description: bytes transferred
ConnectionStatus:
type: object
properties:
username:
type: string
description: connected username
connection_id:
type: string
description: unique connection identifier
2019-07-20 10:26:52 +00:00
client_version:
type: string
description: client version
2019-07-20 10:26:52 +00:00
remote_address:
type: string
description: Remote address for the connected client
2019-07-20 10:26:52 +00:00
connection_time:
type: integer
format: int64
description: connection time as unix timestamp in milliseconds
2020-08-11 21:56:10 +00:00
command:
type: string
2021-01-18 12:24:38 +00:00
description: Last SSH/FTP command or WebDAV method
2019-07-20 10:26:52 +00:00
last_activity:
type: integer
format: int64
description: last client activity as unix timestamp in milliseconds
protocol:
type: string
enum:
- SFTP
- SCP
- SSH
2020-08-11 21:56:10 +00:00
- FTP
- DAV
2019-07-20 10:26:52 +00:00
active_transfers:
type: array
items:
$ref: '#/components/schemas/Transfer'
2019-07-20 10:26:52 +00:00
QuotaScan:
type: object
properties:
username:
type: string
description: username with an active scan
start_time:
type: integer
format: int64
description: scan start time as unix timestamp in milliseconds
FolderQuotaScan:
type: object
properties:
name:
type: string
description: folder name with an active scan
start_time:
type: integer
format: int64
description: scan start time as unix timestamp in milliseconds
SSHHostKey:
type: object
properties:
path:
type: string
fingerprint:
type: string
SSHBinding:
type: object
properties:
address:
type: string
description: TCP address the server listen on
port:
type: integer
description: the port used for serving requests
apply_proxy_config:
type: boolean
description: 'apply the proxy configuration, if any'
WebDAVBinding:
type: object
properties:
address:
type: string
description: TCP address the server listen on
port:
type: integer
description: the port used for serving requests
enable_https:
type: boolean
2020-12-29 18:33:04 +00:00
client_auth_type:
type: integer
description: 1 means that client certificate authentication is required in addition to HTTP basic authentication
FTPDBinding:
type: object
properties:
address:
type: string
description: TCP address the server listen on
port:
type: integer
description: the port used for serving requests
apply_proxy_config:
type: boolean
description: 'apply the proxy configuration, if any'
tls_mode:
type: integer
enum:
- 0
- 1
- 2
description: |
* `0` - clear or explicit TLS * `1` - explicit TLS required * `2` - implicit TLS
force_passive_ip:
type: string
description: External IP address to expose for passive connections
2020-12-29 18:33:04 +00:00
client_auth_type:
type: integer
description: 1 means that client certificate authentication is required in addition to FTP authentication
SSHServiceStatus:
type: object
properties:
is_active:
type: boolean
bindings:
type: array
items:
$ref: '#/components/schemas/SSHBinding'
2021-01-18 12:24:38 +00:00
nullable: true
host_keys:
type: array
items:
$ref: '#/components/schemas/SSHHostKey'
2021-01-18 12:24:38 +00:00
nullable: true
ssh_commands:
2021-01-18 12:24:38 +00:00
type: array
items:
type: string
FTPPassivePortRange:
type: object
properties:
start:
type: integer
end:
type: integer
FTPServiceStatus:
type: object
properties:
is_active:
type: boolean
bindings:
type: array
items:
$ref: '#/components/schemas/FTPDBinding'
2021-01-18 12:24:38 +00:00
nullable: true
passive_port_range:
$ref: '#/components/schemas/FTPPassivePortRange'
WebDAVServiceStatus:
type: object
properties:
is_active:
type: boolean
bindings:
type: array
items:
$ref: '#/components/schemas/WebDAVBinding'
2021-01-18 12:24:38 +00:00
nullable: true
DataProviderStatus:
type: object
properties:
is_active:
type: boolean
driver:
type: string
error:
type: string
ServicesStatus:
type: object
properties:
ssh:
$ref: '#/components/schemas/SSHServiceStatus'
ftp:
$ref: '#/components/schemas/FTPServiceStatus'
webdav:
$ref: '#/components/schemas/WebDAVServiceStatus'
data_provider:
$ref: '#/components/schemas/DataProviderStatus'
2021-01-02 18:33:24 +00:00
defender:
type: object
properties:
is_active:
type: boolean
BanStatus:
type: object
properties:
date_time:
type: string
format: date-time
nullable: true
description: if null the host is not banned
ScoreStatus:
type: object
properties:
score:
type: integer
description: if 0 the host is not listed
2021-01-22 18:42:18 +00:00
BackupData:
type: object
properties:
users:
type: array
items:
$ref: '#/components/schemas/User'
folders:
type: array
items:
$ref: '#/components/schemas/BaseVirtualFolder'
admins:
type: array
items:
$ref: '#/components/schemas/Admin'
version:
type: integer
PwdChange:
type: object
properties:
current_password:
type: string
new_password:
type: string
DirEntry:
type: object
properties:
name:
type: string
description: name of the file (or subdirectory) described by the entry. This name is the final element of the path (the base name), not the entire path
size:
type: integer
format: int64
description: file size, omitted for folders and non regular files
mode:
type: integer
description: |
File mode and permission bits. More details here: https://golang.org/pkg/io/fs/#FileMode.
Let's see some examples:
- for a directory mode&2147483648 != 0
- for a symlink mode&134217728 != 0
- for a regular file mode&2401763328 == 0
last_modified:
type: string
format: date-time
2019-07-20 10:26:52 +00:00
ApiResponse:
type: object
properties:
message:
type: string
description: 'message, can be empty'
2019-07-20 10:26:52 +00:00
error:
type: string
description: error description if any
2019-08-08 08:01:33 +00:00
VersionInfo:
type: object
properties:
version:
type: string
build_date:
type: string
commit_hash:
type: string
features:
type: array
items:
type: string
description: 'Features for the current build. Available features are "portable", "bolt", "mysql", "sqlite", "pgsql", "s3", "gcs", "metrics". If a feature is available it has a "+" prefix, otherwise a "-" prefix'
Token:
type: object
properties:
access_token:
type: string
expires_at:
type: string
format: date-time
securitySchemes:
BasicAuth:
type: http
scheme: basic
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT