beenull/sftpgo-mirror
1
0
Fork 0
mirror of https://github.com/drakkan/sftpgo.git synced 2024-11-22 23:50:32 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6
sftpgo-mirror/openapi/openapi.yaml

6098 lines
205 KiB
YAML
Raw Normal View History

sftpd: update pkg/sftp The patch to open a file in read/write mode is now merged
2020-09-06 09:40:31 +00:00
openapi: 3.0.3
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
tags:
- name: healthcheck
- name: token
- name: maintenance
- name: admins
REST API: add support for API key authentication
2021-08-17 16:08:32 +00:00
- name: API keys
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
- name: connections
- name: defender
- name: quota
- name: folders
add groups support Using groups simplifies the administration of multiple accounts by letting you assign settings once to a group, instead of multiple times to each individual user. Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-04-25 13:49:11 +00:00
- name: groups
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
- name: users
add basic REST APIs for data retention Fixes #495
2021-09-25 10:20:31 +00:00
- name: data retention
plugins: improve notifier and searcher
2021-10-20 17:39:49 +00:00
- name: events
add support for metadata plugins
2021-12-16 17:18:36 +00:00
- name: metadata
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- name: user APIs
- name: public shares
first version
2019-07-20 10:26:52 +00:00
info:
title: SFTPGo
Add a Getting Started Guide
2021-05-20 16:16:27 +00:00
description: |
allow to mount virtual folders on root (/) path Fixes #783 Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-04-02 16:32:46 +00:00
SFTPGo allows you to securely share your files over SFTP and optionally over HTTP/S, FTP/S and WebDAV as well.
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 Google Cloud Storage bucket (or part of it) on a specified path and an encrypted local filesystem on another one.
Add a Getting Started Guide
2021-05-20 16:16:27 +00:00
Virtual folders can be private or shared among multiple users, for shared virtual folders you can define different quota limits for each user.
add groups support Using groups simplifies the administration of multiple accounts by letting you assign settings once to a group, instead of multiple times to each individual user. Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-04-25 13:49:11 +00:00
SFTPGo supports groups to simplify the administration of multiple accounts by letting you assign settings once to a group, instead of multiple times to each individual user.
SFTPGo is now listed on Azure Marketplace Fixes #684 Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-03-17 13:59:02 +00:00
The SFTPGo WebClient allows end users to change their credentials, browse and manage their files in the browser and setup two-factor authentication which works with Authy, Google Authenticator and other compatible apps.
From the WebClient each authorized user can also create HTTP/S links to externally share files and folders securely, by setting limits to the number of downloads/uploads, protecting the share with a password, limiting access by source IP address, setting an automatic expiration date.
set version to 2.3.1 Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-06-10 16:42:13 +00:00
version: 2.3.1
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
contact:
OpenAPI: document that quota-update support partial updates If the update mode is "add" and you pass only used_quota_size or only used_quota_files the missing field will remain unchanged
2021-04-28 17:16:15 +00:00
name: API support
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
url: 'https://github.com/drakkan/sftpgo'
license:
name: AGPLv3
url: 'https://www.gnu.org/licenses/agpl-3.0.en.html'
first version
2019-07-20 10:26:52 +00:00
servers:
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
- url: /api/v2
httpd: add support for basic auth and HTTPS
2020-02-03 23:08:00 +00:00
security:
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
- BearerAuth: []
REST API: add support for API key authentication
2021-08-17 16:08:32 +00:00
- APIKeyAuth: []
first version
2019-07-20 10:26:52 +00:00
paths:
document heathz endpoint
2020-11-01 09:39:10 +00:00
/healthz:
get:
add a dedicated struct to store encrypted credentials also gcs credentials are now encrypted, both on disk and inside the provider. Data provider is automatically migrated and load data will accept old format too but you should upgrade to the new format to avoid future issues
2020-11-22 20:53:04 +00:00
security: []
document heathz endpoint
2020-11-01 09:39:10 +00:00
servers:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
- url: /
document heathz endpoint
2020-11-01 09:39:10 +00:00
tags:
- healthcheck
summary: health check
improve OpenAPI schema so it is better rendered on Stoplight
2021-03-07 17:41:56 +00:00
description: This endpoint can be used to check if the application is running and responding to requests
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
operationId: healthz
document heathz endpoint
2020-11-01 09:39:10 +00:00
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
document heathz endpoint
2020-11-01 09:39:10 +00:00
description: successful operation
content:
text/plain:
schema:
type: string
example: ok
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
/shares/{id}:
parameters:
- name: id
in: path
description: the share id
required: true
schema:
type: string
get:
security:
- BasicAuth: []
tags:
- public shares
summary: Download shared files and folders as a single zip file
description: A zip file, containing the shared 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. The share must be defined with the read scope and the associated user must have list and download permissions
operationId: get_share
web client: allow downloading of single shared files without compression Fixes #629
2021-11-30 19:32:10 +00:00
parameters:
- in: query
name: compress
schema:
type: boolean
default: true
required: false
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
responses:
'200':
description: successful operation
content:
web client: allow downloading of single shared files without compression Fixes #629
2021-11-30 19:32:10 +00:00
'*/*':
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
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'
post:
security:
- BasicAuth: []
tags:
- public shares
summary: Upload one or more files to the shared path
web client: use fetch to upload files also add REST API to upload a single file as POST body
2021-12-08 18:25:22 +00:00
description: The share must be defined with the write scope and the associated user must have the upload permission
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
operationId: upload_to_share
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
filenames:
type: array
items:
type: string
format: binary
minItems: 1
uniqueItems: true
required: true
responses:
'201':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ApiResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
web client: improve file upload
2021-11-22 11:25:36 +00:00
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
make HTTP shares browsable if you share a single folder with read scope, you can now browse the share and download single files Fixes #674 See #677 Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-02-06 15:46:43 +00:00
/shares/{id}/files:
parameters:
- name: id
in: path
description: the share id
required: true
schema:
type: string
get:
security:
- BasicAuth: []
tags:
- public shares
summary: Download a single file
description: Returns the file contents as response body. The share must have exactly one path defined and it must be a directory for this to work
operationId: download_share_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
- in: query
name: inline
required: false
description: 'If set, the response will not have the Content-Disposition header set to `attachment`'
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'
/shares/{id}/dirs:
parameters:
- name: id
in: path
description: the share id
required: true
schema:
type: string
get:
security:
- BasicAuth: []
tags:
- public shares
summary: Read directory contents
description: Returns the contents of the specified directory for the specified share. The share must have exactly one path defined and it must be a directory for this to work
operationId: get_share_dir_contents
parameters:
- in: query
name: path
add support for a start directory Fixes #705 Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-03-03 11:44:56 +00:00
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 user's start directory is assumed. If relative, the user's start directory is used as the base
make HTTP shares browsable if you share a single folder with read scope, you can now browse the share and download single files Fixes #674 See #677 Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-02-06 15:46:43 +00:00
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'
web client: use fetch to upload files also add REST API to upload a single file as POST body
2021-12-08 18:25:22 +00:00
/shares/{id}/{fileName}:
parameters:
- name: id
in: path
description: the share id
required: true
schema:
type: string
- name: fileName
in: path
description: the name of the new file. It must be path encoded. Sub directories are not accepted
required: true
schema:
type: string
- name: X-SFTPGO-MTIME
in: header
schema:
type: integer
description: File modification time as unix timestamp in milliseconds
post:
security:
- BasicAuth: []
tags:
- public shares
summary: Upload a single file to the shared path
description: The share must be defined with the write scope and the associated user must have the upload/overwrite permissions
operationId: upload_single_to_share
requestBody:
content:
application/*:
schema:
type: string
format: binary
text/*:
schema:
type: string
format: binary
image/*:
schema:
type: string
format: binary
audio/*:
schema:
type: string
format: binary
video/*:
schema:
type: string
format: binary
required: true
responses:
'201':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ApiResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
/token:
get:
security:
- BasicAuth: []
tags:
- token
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
summary: Get a new admin access token
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: Returns an access token and its expiration
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
operationId: get_token
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
parameters:
- in: header
name: X-SFTPGO-OTP
schema:
type: string
required: false
description: 'If you have 2FA configured for the admin attempting to log in you need to set the authentication code using this header parameter'
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
description: successful operation
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/Token'
'401':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
REST API: add logout and store invalidated token
2021-01-26 21:35:36 +00:00
/logout:
get:
REST API: add support for API key authentication
2021-08-17 16:08:32 +00:00
security:
- BearerAuth: []
REST API: add logout and store invalidated token
2021-01-26 21:35:36 +00:00
tags:
- token
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
summary: Invalidate an admin access token
description: Allows to invalidate an admin token before its expiration
REST API: add logout and store invalidated token
2021-01-26 21:35:36 +00:00
operationId: logout
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
REST API: add logout and store invalidated token
2021-01-26 21:35:36 +00:00
description: successful operation
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/ApiResponse'
'401':
REST API: add logout and store invalidated token
2021-01-26 21:35:36 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API: add logout and store invalidated token
2021-01-26 21:35:36 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API: add logout and store invalidated token
2021-01-26 21:35:36 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
/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
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
parameters:
- in: header
name: X-SFTPGO-OTP
schema:
type: string
required: false
description: 'If you have 2FA configured, for the HTTP protocol, for the user attempting to log in you need to set the authentication code using this header parameter'
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
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:
REST API: add support for API key authentication
2021-08-17 16:08:32 +00:00
security:
- BearerAuth: []
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
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'
add version info
2019-08-08 08:01:33 +00:00
/version:
get:
tags:
REST API: add a method to get the status of the services added a status page to the built-in web admin
2020-12-08 10:18:34 +00:00
- maintenance
add version info
2019-08-08 08:01:33 +00:00
summary: Get version details
improve OpenAPI schema so it is better rendered on Stoplight
2021-03-07 17:41:56 +00:00
description: 'Returns version details such as the version number, build date, commit hash and enabled features'
add version info
2019-08-08 08:01:33 +00:00
operationId: get_version
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
add version info
2019-08-08 08:01:33 +00:00
description: successful operation
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/VersionInfo'
'401':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
/changepwd/admin:
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
put:
REST API: add support for API key authentication
2021-08-17 16:08:32 +00:00
security:
- BearerAuth: []
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
tags:
- admins
summary: Change admin password
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
description: Changes the password for the logged in admin. Please use '/admin/changepwd' instead
operationId: change_admin_password_deprecated
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
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:
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
put:
REST API: add support for API key authentication
2021-08-17 16:08:32 +00:00
security:
- BearerAuth: []
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
tags:
- admins
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
summary: Change admin password
improve OpenAPI schema so it is better rendered on Stoplight
2021-03-07 17:41:56 +00:00
description: Changes the password for the logged in admin
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
operationId: change_admin_password
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PwdChange'
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
description: successful operation
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/ApiResponse'
'401':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
rework user and admin profiles users and admins can now also update their email and description
2021-09-29 16:46:15 +00:00
/admin/profile:
user: add a permission to disable changing api key authentication also implement the missing APIs to enable/disable api key authentication
2021-09-06 16:46:35 +00:00
get:
security:
- BearerAuth: []
tags:
- admins
web UI: update js and css deps
2021-09-30 08:23:25 +00:00
summary: Get admin profile
rework user and admin profiles users and admins can now also update their email and description
2021-09-29 16:46:15 +00:00
description: 'Returns the profile for the logged in admin'
operationId: get_admin_profile
user: add a permission to disable changing api key authentication also implement the missing APIs to enable/disable api key authentication
2021-09-06 16:46:35 +00:00
responses:
'200':
description: successful operation
content:
application/json:
schema:
rework user and admin profiles users and admins can now also update their email and description
2021-09-29 16:46:15 +00:00
$ref: '#/components/schemas/AdminProfile'
user: add a permission to disable changing api key authentication also implement the missing APIs to enable/disable api key authentication
2021-09-06 16:46:35 +00:00
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
put:
security:
- BearerAuth: []
tags:
- admins
rework user and admin profiles users and admins can now also update their email and description
2021-09-29 16:46:15 +00:00
summary: Update admin profile
description: 'Allows to update the profile for the logged in admin'
operationId: update_admin_profile
user: add a permission to disable changing api key authentication also implement the missing APIs to enable/disable api key authentication
2021-09-06 16:46:35 +00:00
requestBody:
required: true
content:
application/json:
schema:
rework user and admin profiles users and admins can now also update their email and description
2021-09-29 16:46:15 +00:00
$ref: '#/components/schemas/AdminProfile'
user: add a permission to disable changing api key authentication also implement the missing APIs to enable/disable api key authentication
2021-09-06 16:46:35 +00:00
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'
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
/admin/2fa/recoverycodes:
get:
security:
- BearerAuth: []
tags:
- admins
summary: Get recovery codes
description: 'Returns the recovery codes for the logged in admin. Recovery codes can be used if the admin loses access to their second factor auth device. Recovery codes are returned unencrypted'
operationId: get_admin_recovery_codes
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RecoveryCode'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
post:
security:
- BearerAuth: []
tags:
- admins
summary: Generate recovery codes
description: 'Generates new recovery codes for the logged in admin. Generating new recovery codes you automatically invalidate old ones'
operationId: generate_admin_recovery_codes
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'
/admin/totp/configs:
get:
security:
- BearerAuth: []
tags:
- admins
summary: Get available TOTP configuration
description: Returns the available TOTP configurations for the logged in admin
operationId: get_admin_totp_configs
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TOTPConfig'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/admin/totp/generate:
post:
security:
- BearerAuth: []
tags:
- admins
summary: Generate a new TOTP secret
description: 'Generates a new TOTP secret, including the QR code as png, using the specified configuration for the logged in admin'
operationId: generate_admin_totp_secret
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
config_name:
type: string
description: 'name of the configuration to use to generate the secret'
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: object
properties:
config_name:
type: string
issuer:
type: string
secret:
type: string
qr_code:
type: string
format: byte
description: 'QR code png encoded as BASE64'
'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'
/admin/totp/validate:
post:
security:
- BearerAuth: []
tags:
- admins
summary: Validate a one time authentication code
description: 'Checks if the given authentication code can be validated using the specified secret and config name'
operationId: validate_admin_totp_secret
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
config_name:
type: string
description: 'name of the configuration to use to validate the passcode'
passcode:
type: string
description: 'passcode to validate'
secret:
type: string
description: 'secret to use to validate the passcode'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
message: Passcode successfully validated
'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'
/admin/totp/save:
post:
security:
- BearerAuth: []
tags:
- admins
summary: Save a TOTP config
description: 'Saves the specified TOTP config for the logged in admin'
operationId: save_admin_totp_config
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AdminTOTPConfig'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
message: TOTP configuration saved
'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'
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
/connections:
first version
2019-07-20 10:26:52 +00:00
get:
tags:
document heathz endpoint
2020-11-01 09:39:10 +00:00
- connections
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
summary: Get connections details
improve OpenAPI schema so it is better rendered on Stoplight
2021-03-07 17:41:56 +00:00
description: Returns the active users and info about their current uploads/downloads
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 12:41:15 +00:00
operationId: get_connections
first version
2019-07-20 10:26:52 +00:00
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
first version
2019-07-20 10:26:52 +00:00
description: successful operation
content:
application/json:
schema:
type: array
items:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/ConnectionStatus'
'401':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'/connections/{connectionID}':
first version
2019-07-20 10:26:52 +00:00
delete:
tags:
document heathz endpoint
2020-11-01 09:39:10 +00:00
- connections
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
summary: Close connection
improve OpenAPI schema so it is better rendered on Stoplight
2021-03-07 17:41:56 +00:00
description: Terminates an active connection
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 12:41:15 +00:00
operationId: close_connection
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 10:36:21 +00:00
parameters:
document heathz endpoint
2020-11-01 09:39:10 +00:00
- name: connectionID
in: path
description: ID of the connection to close
required: true
schema:
type: string
first version
2019-07-20 10:26:52 +00:00
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
first version
2019-07-20 10:26:52 +00:00
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 10:36:21 +00:00
example:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
message: Connection closed
'401':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'404':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/NotFound'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
/defender/hosts:
get:
tags:
- defender
summary: Get hosts
description: Returns hosts that are banned or for which some violations have been detected
operationId: get_defender_hosts
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DefenderEntry'
'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/hosts/{id}:
parameters:
- name: id
in: path
description: host id
required: true
schema:
type: string
get:
tags:
- defender
summary: Get host by id
description: Returns the host with the given id, if it exists
operationId: get_defender_host_by_id
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/DefenderEntry'
'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:
- defender
summary: Removes a host from the defender lists
description: Unbans the specified host or clears its violations
operationId: delete_defender_host_by_id
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
'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'
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
/defender/bantime:
add REST API for the defender
2021-01-02 18:33:24 +00:00
get:
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
deprecated: true
add REST API for the defender
2021-01-02 18:33:24 +00:00
tags:
- defender
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
summary: Get ban time
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
description: Deprecated, please use '/defender/hosts', '/defender/hosts/{id}' instead
add REST API for the defender
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:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
add REST API for the defender
2021-01-02 18:33:24 +00:00
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/BanStatus'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
add REST API for the defender
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
add REST API for the defender
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'404':
add REST API for the defender
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/NotFound'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
add REST API for the defender
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/defender/unban:
post:
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
deprecated: true
add REST API for the defender
2021-01-02 18:33:24 +00:00
tags:
- defender
improve OpenAPI schema so it is better rendered on Stoplight
2021-03-07 17:41:56 +00:00
summary: Unban
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
description: Deprecated, please use '/defender/hosts/{id}' instead
add REST API for the defender
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:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
add REST API for the defender
2021-01-02 18:33:24 +00:00
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'400':
add REST API for the defender
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/BadRequest'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
add REST API for the defender
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
add REST API for the defender
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'404':
add REST API for the defender
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/NotFound'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
add REST API for the defender
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/defender/score:
get:
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
deprecated: true
add REST API for the defender
2021-01-02 18:33:24 +00:00
tags:
- defender
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
summary: Get score
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
description: Deprecated, please use '/defender/hosts', '/defender/hosts/{id}' instead
add REST API for the defender
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:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
add REST API for the defender
2021-01-02 18:33:24 +00:00
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ScoreStatus'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
add REST API for the defender
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
add REST API for the defender
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'404':
add REST API for the defender
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/NotFound'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
add REST API for the defender
2021-01-02 18:33:24 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
add support for metadata plugins
2021-12-16 17:18:36 +00:00
/metadata/users/checks:
get:
tags:
- metadata
summary: Get metadata checks
description: Returns the active metadata checks
operationId: get_users_metadata_checks
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/MetadataCheck'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/metadata/users/{username}/check:
parameters:
- name: username
in: path
description: the username
required: true
schema:
type: string
post:
tags:
- metadata
summary: Start a metadata check
description: 'Starts a new metadata check for the given user. A metadata check requires a metadata plugin and removes the metadata associated to missing items (for example objects deleted outside SFTPGo). If a metadata check for this user is already active a 409 status code is returned. Metadata are stored for cloud storage backends. This API does nothing for other backends or if no metadata plugin is configured'
operationId: start_user_metadata_check
responses:
'202':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
message: Check 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'
add basic REST APIs for data retention Fixes #495
2021-09-25 10:20:31 +00:00
/retention/users/checks:
get:
tags:
- data retention
summary: Get retention checks
description: Returns the active retention checks
operationId: get_users_retention_checks
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RetentionCheck'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/retention/users/{username}/check:
parameters:
- name: username
in: path
description: the username
required: true
schema:
type: string
add data retention check hook
2021-10-03 13:17:49 +00:00
- name: notifications
data retention: allow to notify results via e-mail
2021-10-02 20:25:41 +00:00
in: query
add data retention check hook
2021-10-03 13:17:49 +00:00
description: 'specify how to notify results'
explode: false
data retention: allow to notify results via e-mail
2021-10-02 20:25:41 +00:00
schema:
add data retention check hook
2021-10-03 13:17:49 +00:00
type: array
items:
$ref: '#/components/schemas/RetentionCheckNotification'
add basic REST APIs for data retention Fixes #495
2021-09-25 10:20:31 +00:00
post:
tags:
- data retention
summary: Start a retention check
description: 'Starts a new retention check for the given user. If a retention check for this user is already active a 409 status code is returned'
operationId: start_user_retention_check
requestBody:
required: true
description: 'Defines virtual paths to check and their retention time in hours'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FolderRetention'
responses:
'202':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
message: Check 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'
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
/quotas/users/scans:
get:
tags:
- quota
summary: Get active user quota scans
description: Returns the active user quota scans
operationId: get_users_quota_scans
responses:
'200':
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'
/quotas/users/{username}/scan:
parameters:
- name: username
in: path
description: the username
required: true
schema:
type: string
post:
tags:
- quota
summary: Start a 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
operationId: start_user_quota_scan
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'
/quotas/users/{username}/usage:
parameters:
- name: username
in: path
description: the username
required: true
schema:
type: string
- 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
put:
tags:
- quota
add support for data transfer bandwidth limits with total limit or separate settings for uploads and downloads and overrides based on the client's IP address. Limits can be reset using the REST API Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-01-30 10:42:36 +00:00
summary: Update disk quota usage limits
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
description: Sets the current used quota limits for the given user
operationId: user_quota_update_usage
requestBody:
required: true
description: 'If used_quota_size and used_quota_files are missing they will default to 0, this means that if mode is "add" the current value, for the missing field, will remain unchanged, if mode is "reset" the missing field is set to 0'
content:
application/json:
schema:
$ref: '#/components/schemas/QuotaUsage'
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'
add support for data transfer bandwidth limits with total limit or separate settings for uploads and downloads and overrides based on the client's IP address. Limits can be reset using the REST API Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-01-30 10:42:36 +00:00
/quotas/users/{username}/transfer-usage:
parameters:
- name: username
in: path
description: the username
required: true
schema:
type: string
- 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
put:
tags:
- quota
summary: Update transfer quota usage limits
description: Sets the current used transfer quota limits for the given user
operationId: user_transfer_quota_update_usage
requestBody:
required: true
description: 'If used_upload_data_transfer and used_download_data_transfer are missing they will default to 0, this means that if mode is "add" the current value, for the missing field, will remain unchanged, if mode is "reset" the missing field is set to 0'
content:
application/json:
schema:
$ref: '#/components/schemas/TransferQuotaUsage'
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'
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
/quotas/folders/scans:
get:
tags:
- quota
summary: Get active folder quota scans
description: Returns the active folder quota scans
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'
/quotas/folders/{name}/scan:
parameters:
- name: name
in: path
description: folder name
required: true
schema:
type: string
post:
tags:
- quota
summary: Start a 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
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'
/quotas/folders/{name}/usage:
parameters:
- name: name
in: path
description: folder name
required: true
schema:
type: string
- 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
put:
tags:
- quota
summary: Update folder quota usage limits
description: Sets the current used quota limits for the given folder
operationId: folder_quota_update_usage
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: 'If used_quota_size and used_quota_files are missing they will default to 0, this means that if mode is "add" the current value, for the missing field, will remain unchanged, if mode is "reset" the missing field is set to 0'
content:
application/json:
schema:
$ref: '#/components/schemas/QuotaUsage'
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'
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
/quota-scans:
first version
2019-07-20 10:26:52 +00:00
get:
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
deprecated: true
first version
2019-07-20 10:26:52 +00:00
tags:
document heathz endpoint
2020-11-01 09:39:10 +00:00
- quota
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
summary: Get quota scans
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
description: Deprecated, please use '/quotas/users/scans' instead
operationId: get_users_quota_scans_deprecated
first version
2019-07-20 10:26:52 +00:00
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
first version
2019-07-20 10:26:52 +00:00
description: successful operation
content:
application/json:
schema:
type: array
items:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/QuotaScan'
'401':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
first version
2019-07-20 10:26:52 +00:00
post:
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
deprecated: true
first version
2019-07-20 10:26:52 +00:00
tags:
document heathz endpoint
2020-11-01 09:39:10 +00:00
- quota
improve OpenAPI schema so it is better rendered on Stoplight
2021-03-07 17:41:56 +00:00
summary: Start user quota scan
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
description: Deprecated, please use '/quotas/users/{username}/scan' instead
operationId: start_user_quota_scan_deprecated
first version
2019-07-20 10:26:52 +00:00
requestBody:
required: true
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/User'
first version
2019-07-20 10:26:52 +00:00
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'202':
first version
2019-07-20 10:26:52 +00:00
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 10:36:21 +00:00
example:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
message: Scan started
'400':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/BadRequest'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'404':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/NotFound'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'409':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Conflict'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
/quota-update:
Add API endpoint to set current quota Fixes #130
2020-06-20 10:38:04 +00:00
put:
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
deprecated: true
Add API endpoint to set current quota Fixes #130
2020-06-20 10:38:04 +00:00
tags:
document heathz endpoint
2020-11-01 09:39:10 +00:00
- quota
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
summary: Update quota usage limits
description: Deprecated, please use '/quotas/users/{username}/usage' instead
operationId: user_quota_update_usage_deprecated
Add API endpoint to set current quota Fixes #130
2020-06-20 10:38:04 +00:00
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
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
enum:
- add
- reset
description: |
Add API endpoint to set current quota Fixes #130
2020-06-20 10:38:04 +00:00
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
OpenAPI: document that quota-update support partial updates If the update mode is "add" and you pass only used_quota_size or only used_quota_files the missing field will remain unchanged
2021-04-28 17:16:15 +00:00
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'
Add API endpoint to set current quota Fixes #130
2020-06-20 10:38:04 +00:00
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/User'
Add API endpoint to set current quota Fixes #130
2020-06-20 10:38:04 +00:00
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
Add API endpoint to set current quota Fixes #130
2020-06-20 10:38:04 +00:00
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
message: Quota updated
'400':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/BadRequest'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'404':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/NotFound'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
/folder-quota-update:
Add API endpoint to set current quota Fixes #130
2020-06-20 10:38:04 +00:00
put:
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
deprecated: true
Add API endpoint to set current quota Fixes #130
2020-06-20 10:38:04 +00:00
tags:
document heathz endpoint
2020-11-01 09:39:10 +00:00
- quota
improve OpenAPI schema so it is better rendered on Stoplight
2021-03-07 17:41:56 +00:00
summary: Update folder quota limits
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
description: Deprecated, please use '/quotas/folders/{name}/usage' instead
operationId: folder_quota_update_usage_deprecated
Add API endpoint to set current quota Fixes #130
2020-06-20 10:38:04 +00:00
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
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
enum:
- add
- reset
description: |
Add API endpoint to set current quota Fixes #130
2020-06-20 10:38:04 +00:00
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
OpenAPI: document that also folder-quota-update supports partial updates
2021-04-28 17:33:32 +00:00
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'
Add API endpoint to set current quota Fixes #130
2020-06-20 10:38:04 +00:00
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/BaseVirtualFolder'
Add API endpoint to set current quota Fixes #130
2020-06-20 10:38:04 +00:00
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
Add API endpoint to set current quota Fixes #130
2020-06-20 10:38:04 +00:00
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
message: Quota updated
'400':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/BadRequest'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'404':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/NotFound'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
/folder-quota-scans:
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
get:
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
deprecated: true
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
tags:
document heathz endpoint
2020-11-01 09:39:10 +00:00
- quota
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
summary: Get folders quota scans
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
description: Deprecated, please use '/quotas/folders/scans' instead
operationId: get_folders_quota_scans_deprecated
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
description: successful operation
content:
application/json:
schema:
type: array
items:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/FolderQuotaScan'
'401':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
post:
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
deprecated: true
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
tags:
document heathz endpoint
2020-11-01 09:39:10 +00:00
- quota
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
summary: Start a folder quota scan
description: Deprecated, please use '/quotas/folders/{name}/scan' instead
operationId: start_folder_quota_scan_deprecated
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
requestBody:
required: true
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/BaseVirtualFolder'
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'202':
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
message: Scan started
'400':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/BadRequest'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'404':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/NotFound'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'409':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Conflict'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
/folders:
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
get:
tags:
document heathz endpoint
2020-11-01 09:39:10 +00:00
- folders
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
summary: Get folders
description: Returns an array with one or more folders
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
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
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: 'The maximum number of items to return. Max value is 500, default is 100'
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
- in: query
name: order
required: false
add groups support Using groups simplifies the administration of multiple accounts by letting you assign settings once to a group, instead of multiple times to each individual user. Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-04-25 13:49:11 +00:00
description: Ordering folders by name. Default ASC
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
type: string
enum:
- ASC
- DESC
example: ASC
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
description: successful operation
content:
application/json:
schema:
type: array
items:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/BaseVirtualFolder'
'400':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/BadRequest'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
post:
tags:
document heathz endpoint
2020-11-01 09:39:10 +00:00
- folders
improve OpenAPI schema so it is better rendered on Stoplight
2021-03-07 17:41:56 +00:00
summary: Add folder
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
operationId: add_folder
improve OpenAPI schema so it is better rendered on Stoplight
2021-03-07 17:41:56 +00:00
description: Adds a new folder. A quota scan is required to update the used files/size
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
requestBody:
required: true
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/BaseVirtualFolder'
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'201':
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
description: successful operation
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/BaseVirtualFolder'
'400':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/BadRequest'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'/folders/{name}':
virtual folders: change dataprovider structure This way we no longer depend on the local file system path and so we can add support for cloud backends in future updates
2021-02-01 18:04:15 +00:00
parameters:
- name: name
in: path
description: folder name
required: true
schema:
type: string
get:
tags:
- folders
improve OpenAPI schema so it is better rendered on Stoplight
2021-03-07 17:41:56 +00:00
summary: Find folders by name
description: Returns the folder with the given name if it exists.
virtual folders: change dataprovider structure This way we no longer depend on the local file system path and so we can add support for cloud backends in future updates
2021-02-01 18:04:15 +00:00
operationId: get_folder_by_name
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
virtual folders: change dataprovider structure This way we no longer depend on the local file system path and so we can add support for cloud backends in future updates
2021-02-01 18:04:15 +00:00
description: successful operation
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/BaseVirtualFolder'
'400':
virtual folders: change dataprovider structure This way we no longer depend on the local file system path and so we can add support for cloud backends in future updates
2021-02-01 18:04:15 +00:00
$ref: '#/components/responses/BadRequest'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
virtual folders: change dataprovider structure This way we no longer depend on the local file system path and so we can add support for cloud backends in future updates
2021-02-01 18:04:15 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
virtual folders: change dataprovider structure This way we no longer depend on the local file system path and so we can add support for cloud backends in future updates
2021-02-01 18:04:15 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'404':
virtual folders: change dataprovider structure This way we no longer depend on the local file system path and so we can add support for cloud backends in future updates
2021-02-01 18:04:15 +00:00
$ref: '#/components/responses/NotFound'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
virtual folders: change dataprovider structure This way we no longer depend on the local file system path and so we can add support for cloud backends in future updates
2021-02-01 18:04:15 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
put:
tags:
- folders
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
summary: Update folder
improve OpenAPI schema so it is better rendered on Stoplight
2021-03-07 17:41:56 +00:00
description: Updates an existing folder
virtual folders: change dataprovider structure This way we no longer depend on the local file system path and so we can add support for cloud backends in future updates
2021-02-01 18:04:15 +00:00
operationId: update_folder
requestBody:
required: true
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/BaseVirtualFolder'
virtual folders: change dataprovider structure This way we no longer depend on the local file system path and so we can add support for cloud backends in future updates
2021-02-01 18:04:15 +00:00
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
virtual folders: change dataprovider structure This way we no longer depend on the local file system path and so we can add support for cloud backends in future updates
2021-02-01 18:04:15 +00:00
description: successful operation
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/ApiResponse'
virtual folders: change dataprovider structure This way we no longer depend on the local file system path and so we can add support for cloud backends in future updates
2021-02-01 18:04:15 +00:00
example:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
message: User updated
'400':
virtual folders: change dataprovider structure This way we no longer depend on the local file system path and so we can add support for cloud backends in future updates
2021-02-01 18:04:15 +00:00
$ref: '#/components/responses/BadRequest'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
virtual folders: change dataprovider structure This way we no longer depend on the local file system path and so we can add support for cloud backends in future updates
2021-02-01 18:04:15 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
virtual folders: change dataprovider structure This way we no longer depend on the local file system path and so we can add support for cloud backends in future updates
2021-02-01 18:04:15 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'404':
virtual folders: change dataprovider structure This way we no longer depend on the local file system path and so we can add support for cloud backends in future updates
2021-02-01 18:04:15 +00:00
$ref: '#/components/responses/NotFound'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
virtual folders: change dataprovider structure This way we no longer depend on the local file system path and so we can add support for cloud backends in future updates
2021-02-01 18:04:15 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
delete:
tags:
document heathz endpoint
2020-11-01 09:39:10 +00:00
- folders
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
summary: Delete folder
improve OpenAPI schema so it is better rendered on Stoplight
2021-03-07 17:41:56 +00:00
description: Deletes an existing folder
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
operationId: delete_folder
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
description: successful operation
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/ApiResponse'
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
example:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
message: User deleted
'400':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/BadRequest'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'404':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/NotFound'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
add groups support Using groups simplifies the administration of multiple accounts by letting you assign settings once to a group, instead of multiple times to each individual user. Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-04-25 13:49:11 +00:00
/groups:
get:
tags:
- groups
summary: Get groups
description: Returns an array with one or more groups
operationId: get_groups
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 groups by name. 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/Group'
'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:
- groups
summary: Add group
operationId: add_group
description: Adds a new group
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
responses:
'201':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
'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'
'/groups/{name}':
parameters:
- name: name
in: path
description: group name
required: true
schema:
type: string
get:
tags:
- groups
summary: Find groups by name
description: Returns the group with the given name if it exists.
operationId: get_group_by_name
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
'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:
- groups
summary: Update group
description: Updates an existing group
operationId: update_group
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
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:
- groups
summary: Delete
description: Deletes an existing group
operationId: delete_group
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'
plugins: improve notifier and searcher
2021-10-20 17:39:49 +00:00
/events/fs:
get:
tags:
- events
summary: Get filesystem events
description: 'Returns an array with one or more filesystem events applying the specified filters. This API is only available if you configure an "eventsearcher" plugin'
operationId: get_fs_events
parameters:
- in: query
name: start_timestamp
schema:
type: integer
format: int64
minimum: 0
default: 0
required: false
description: 'the event timestamp, unix timestamp in nanoseconds, must be greater than or equal to the specified one. 0 or missing means omit this filter'
- in: query
name: end_timestamp
schema:
type: integer
format: int64
minimum: 0
default: 0
required: false
description: 'the event timestamp, unix timestamp in nanoseconds, must be less than or equal to the specified one. 0 or missing means omit this filter'
- in: query
name: actions
schema:
type: array
items:
$ref: '#/components/schemas/FsEventAction'
description: 'the event action must be included among those specified. Empty or missing means omit this filter. Actions must be specified comma separated'
explode: false
required: false
- in: query
name: username
schema:
type: string
description: 'the event username must be the same as the one specified. Empty or missing means omit this filter'
required: false
- in: query
name: ip
schema:
type: string
description: 'the event IP must be the same as the one specified. Empty or missing means omit this filter'
required: false
- in: query
name: ssh_cmd
schema:
type: string
description: 'the event SSH command must be the same as the one specified. Empty or missing means omit this filter'
required: false
eventsearcher plugin: add support to search for provider, bucket, endpoint Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-01-03 16:02:52 +00:00
- in: query
name: fs_provider
schema:
doc improvements and minor changes Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-01-16 08:50:23 +00:00
$ref: '#/components/schemas/FsProviders'
eventsearcher plugin: add support to search for provider, bucket, endpoint Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-01-03 16:02:52 +00:00
description: 'the event filesystem provider must be the same as the one specified. Empty or missing means omit this filter'
required: false
- in: query
name: bucket
schema:
type: string
description: 'the bucket must be the same as the one specified. Empty or missing means omit this filter'
required: false
- in: query
name: endpoint
schema:
type: string
description: 'the endpoint must be the same as the one specified. Empty or missing means omit this filter'
required: false
plugins: improve notifier and searcher
2021-10-20 17:39:49 +00:00
- in: query
name: protocols
schema:
type: array
items:
$ref: '#/components/schemas/EventProtocols'
description: 'the event protocol must be included among those specified. Empty or missing means omit this filter. Values must be specified comma separated'
explode: false
required: false
- in: query
name: statuses
schema:
type: array
items:
$ref: '#/components/schemas/FsEventStatus'
description: 'the event status must be included among those specified. Empty or missing means omit this filter. Values must be specified comma separated'
explode: false
required: false
- in: query
name: instance_ids
schema:
type: array
items:
type: string
description: 'the event instance id must be included among those specified. Empty or missing means omit this filter. Values must be specified comma separated'
explode: false
required: false
- in: query
name: exclude_ids
schema:
type: array
items:
type: string
description: 'the event id must not be included among those specified. This is useful for cursor based pagination. Empty or missing means omit this filter. Values must be specified comma separated'
explode: false
required: false
- in: query
name: limit
schema:
type: integer
minimum: 1
maximum: 1000
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 events by timestamp. Default DESC
schema:
type: string
enum:
- ASC
- DESC
example: DESC
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FsEvent'
'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'
/events/provider:
get:
tags:
- events
summary: Get provider events
description: 'Returns an array with one or more provider events applying the specified filters. This API is only available if you configure an "eventsearcher" plugin'
operationId: get_provider_events
parameters:
- in: query
name: start_timestamp
schema:
type: integer
format: int64
minimum: 0
default: 0
required: false
description: 'the event timestamp, unix timestamp in nanoseconds, must be greater than or equal to the specified one. 0 or missing means omit this filter'
- in: query
name: end_timestamp
schema:
type: integer
format: int64
minimum: 0
default: 0
required: false
description: 'the event timestamp, unix timestamp in nanoseconds, must be less than or equal to the specified one. 0 or missing means omit this filter'
- in: query
name: actions
schema:
type: array
items:
$ref: '#/components/schemas/ProviderEventAction'
description: 'the event action must be included among those specified. Empty or missing means omit this filter. Actions must be specified comma separated'
explode: false
required: false
- in: query
name: username
schema:
type: string
description: 'the event username must be the same as the one specified. Empty or missing means omit this filter'
required: false
- in: query
name: ip
schema:
type: string
description: 'the event IP must be the same as the one specified. Empty or missing means omit this filter'
required: false
- in: query
name: object_name
schema:
type: string
description: 'the event object name must be the same as the one specified. Empty or missing means omit this filter'
required: false
- in: query
name: object_types
schema:
type: array
items:
$ref: '#/components/schemas/ProviderEventObjectType'
description: 'the event object type must be included among those specified. Empty or missing means omit this filter. Values must be specified comma separated'
explode: false
required: false
- in: query
name: instance_ids
schema:
type: array
items:
type: string
description: 'the event instance id must be included among those specified. Empty or missing means omit this filter. Values must be specified comma separated'
explode: false
required: false
- in: query
name: exclude_ids
schema:
type: array
items:
type: string
description: 'the event id must not be included among those specified. This is useful for cursor based pagination. Empty or missing means omit this filter. Values must be specified comma separated'
explode: false
required: false
- in: query
name: limit
schema:
type: integer
minimum: 1
maximum: 1000
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 events by timestamp. Default DESC
schema:
type: string
enum:
- ASC
- DESC
example: DESC
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ProviderEvent'
'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'
REST API: add support for API key authentication
2021-08-17 16:08:32 +00:00
/apikeys:
get:
security:
- BearerAuth: []
tags:
- API keys
summary: Get API keys
description: Returns an array with one or more API keys. For security reasons hashed keys are omitted in the response
operationId: get_api_keys
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 API keys by id. 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/APIKey'
'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:
security:
- BearerAuth: []
tags:
- API keys
summary: Add API key
description: Adds a new API key
operationId: add_api_key
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/APIKey'
responses:
'201':
description: successful operation
headers:
X-Object-ID:
schema:
type: string
description: ID for the new created API key
Location:
schema:
type: string
description: URL to retrieve the details for the new created API key
content:
application/json:
schema:
type: object
properties:
mesage:
type: string
example: 'API key created. This is the only time the API key is visible, please save it.'
key:
type: string
description: 'generated API key'
'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'
'/apikeys/{id}':
parameters:
- name: id
in: path
description: the key id
required: true
schema:
type: string
get:
security:
- BearerAuth: []
tags:
- API keys
summary: Find API key by id
description: Returns the API key with the given id, if it exists. For security reasons the hashed key is omitted in the response
operationId: get_api_key_by_id
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/APIKey'
'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:
security:
- BearerAuth: []
tags:
- API keys
summary: Update API key
description: Updates an existing API key. You cannot update the key itself, the creation date and the last use
operationId: update_api_key
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/APIKey'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
message: API key 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:
security:
- BearerAuth: []
tags:
- API keys
summary: Delete API key
description: Deletes an existing API key
operationId: delete_api_key
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'
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
/admins:
first version
2019-07-20 10:26:52 +00:00
get:
tags:
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
- admins
improve OpenAPI schema so it is better rendered on Stoplight
2021-03-07 17:41:56 +00:00
summary: Get admins
description: Returns an array with one or more admins. For security reasons hashed passwords are omitted in the response
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
operationId: get_admins
first version
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
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: 'The maximum number of items to return. Max value is 500, default is 100'
first version
2019-07-20 10:26:52 +00:00
- in: query
name: order
required: false
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
description: Ordering admins by username. Default ASC
first version
2019-07-20 10:26:52 +00:00
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
type: string
enum:
- ASC
- DESC
example: ASC
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
description: successful operation
content:
application/json:
schema:
type: array
items:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/Admin'
'400':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/BadRequest'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
post:
tags:
- admins
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
summary: Add admin
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
description: 'Adds a new admin. Recovery codes and TOTP configuration cannot be set using this API: each admin must use the specific APIs'
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
operationId: add_admin
requestBody:
required: true
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$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
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'201':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
description: successful operation
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/Admin'
'400':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/BadRequest'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'/admins/{username}':
virtual folders: change dataprovider structure This way we no longer depend on the local file system path and so we can add support for cloud backends in future updates
2021-02-01 18:04:15 +00:00
parameters:
- name: username
in: path
description: the admin username
required: true
schema:
type: string
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
get:
tags:
- admins
improve OpenAPI schema so it is better rendered on Stoplight
2021-03-07 17:41:56 +00:00
summary: Find admins by username
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
description: 'Returns the admin with the given username, if it exists. For security reasons the hashed password is omitted in the response'
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
operationId: get_admin_by_username
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
description: successful operation
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/Admin'
'400':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/BadRequest'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'404':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/NotFound'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
put:
tags:
- admins
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
summary: Update admin
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
description: 'Updates an existing admin. Recovery codes and TOTP configuration cannot be set/updated using this API: each admin must use the specific APIs. You are not allowed to update the admin impersonated using an API key'
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
operationId: update_admin
requestBody:
required: true
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/Admin'
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
description: successful operation
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/ApiResponse'
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
example:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
message: Admin updated
'400':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/BadRequest'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'404':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/NotFound'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
delete:
tags:
- admins
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
summary: Delete admin
improve OpenAPI schema so it is better rendered on Stoplight
2021-03-07 17:41:56 +00:00
description: Deletes an existing admin
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
operationId: delete_admin
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
description: successful operation
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/ApiResponse'
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
example:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
message: Admin deleted
'400':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/BadRequest'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'404':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/NotFound'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
'/admins/{username}/2fa/disable':
parameters:
- name: username
in: path
description: the admin username
required: true
schema:
type: string
put:
tags:
- admins
summary: Disable second factor authentication
description: 'Disables second factor authentication for the given admin. This API must be used if the admin loses access to their second factor auth device and has no recovery codes'
operationId: disable_admin_2fa
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
message: 2FA disabled
'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'
web UI/REST API: add password reset In order to reset the password from the admin/client user interface, an SMTP configuration must be added and the user/admin must have an email address. You can prohibit the reset functionality on a per-user basis by using a specific restriction. Fixes #597
2021-11-13 12:25:43 +00:00
'/admins/{username}/forgot-password':
parameters:
- name: username
in: path
description: the admin username
required: true
schema:
type: string
post:
security: []
tags:
- admins
summary: Send a password reset code by email
description: 'You must set up an SMTP server and the account must have a valid email address, in which case SFTPGo will send a code via email to reset the password. If the specified admin does not exist, the request will be silently ignored (a success response will be returned) to avoid disclosing existing admins'
operationId: admin_forgot_password
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'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
'/admins/{username}/reset-password':
parameters:
- name: username
in: path
description: the admin username
required: true
schema:
type: string
post:
security: []
tags:
- admins
summary: Reset the password
description: 'Set a new password using the code received via email'
operationId: admin_reset_password
requestBody:
content:
application/json:
schema:
type: object
properties:
code:
type: string
password:
type: string
required: true
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'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
/users:
get:
tags:
- users
improve OpenAPI schema so it is better rendered on Stoplight
2021-03-07 17:41:56 +00:00
summary: Get users
description: Returns an array with one or more users. For security reasons hashed passwords are omitted in the response
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
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
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: 'The maximum number of items to return. Max value is 500, default is 100'
first version
2019-07-20 10:26:52 +00:00
- in: query
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
name: order
first version
2019-07-20 10:26:52 +00:00
required: false
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
description: Ordering users by username. Default ASC
first version
2019-07-20 10:26:52 +00:00
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
type: string
enum:
- ASC
- DESC
example: ASC
first version
2019-07-20 10:26:52 +00:00
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
first version
2019-07-20 10:26:52 +00:00
description: successful operation
content:
application/json:
schema:
type: array
items:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/User'
'400':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/BadRequest'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
first version
2019-07-20 10:26:52 +00:00
post:
tags:
document heathz endpoint
2020-11-01 09:39:10 +00:00
- users
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
summary: Add user
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
description: 'Adds a new user.Recovery codes and TOTP configuration cannot be set using this API: each user must use the specific APIs'
first version
2019-07-20 10:26:52 +00:00
operationId: add_user
requestBody:
required: true
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/User'
first version
2019-07-20 10:26:52 +00:00
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'201':
first version
2019-07-20 10:26:52 +00:00
description: successful operation
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/User'
'400':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/BadRequest'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'/users/{username}':
virtual folders: change dataprovider structure This way we no longer depend on the local file system path and so we can add support for cloud backends in future updates
2021-02-01 18:04:15 +00:00
parameters:
- name: username
in: path
description: the username
required: true
schema:
type: string
first version
2019-07-20 10:26:52 +00:00
get:
tags:
document heathz endpoint
2020-11-01 09:39:10 +00:00
- users
improve OpenAPI schema so it is better rendered on Stoplight
2021-03-07 17:41:56 +00:00
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
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
operationId: get_user_by_username
first version
2019-07-20 10:26:52 +00:00
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
first version
2019-07-20 10:26:52 +00:00
description: successful operation
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/User'
'400':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/BadRequest'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'404':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/NotFound'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
first version
2019-07-20 10:26:52 +00:00
put:
tags:
document heathz endpoint
2020-11-01 09:39:10 +00:00
- users
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
summary: Update user
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
description: 'Updates an existing user and optionally disconnects it, if connected, to apply the new settings. Recovery codes and TOTP configuration cannot be set/updated using this API: each user must use the specific APIs'
convert public key from newline delimited string to a real array Added a compatibility layer that will convert newline delimited keys to array when the user is fetched from the database. This code will be removed in future versions please update your public keys, you only need to resave the users using the REST API.
2019-08-01 20:42:46 +00:00
operationId: update_user
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 10:36:21 +00:00
parameters:
document heathz endpoint
2020-11-01 09:39:10 +00:00
- in: query
name: disconnect
schema:
type: integer
enum:
- 0
- 1
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: |
document heathz endpoint
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
first version
2019-07-20 10:26:52 +00:00
requestBody:
required: true
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/User'
first version
2019-07-20 10:26:52 +00:00
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
first version
2019-07-20 10:26:52 +00:00
description: successful operation
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 10:36:21 +00:00
example:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
message: User updated
'400':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/BadRequest'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'404':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/NotFound'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
first version
2019-07-20 10:26:52 +00:00
delete:
tags:
document heathz endpoint
2020-11-01 09:39:10 +00:00
- users
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
summary: Delete user
improve OpenAPI schema so it is better rendered on Stoplight
2021-03-07 17:41:56 +00:00
description: Deletes an existing user
convert public key from newline delimited string to a real array Added a compatibility layer that will convert newline delimited keys to array when the user is fetched from the database. This code will be removed in future versions please update your public keys, you only need to resave the users using the REST API.
2019-08-01 20:42:46 +00:00
operationId: delete_user
first version
2019-07-20 10:26:52 +00:00
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
first version
2019-07-20 10:26:52 +00:00
description: successful operation
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/ApiResponse'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 10:36:21 +00:00
example:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
message: User deleted
'400':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/BadRequest'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'404':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/NotFound'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
'/users/{username}/2fa/disable':
parameters:
- name: username
in: path
description: the username
required: true
schema:
type: string
put:
tags:
- users
summary: Disable second factor authentication
description: 'Disables second factor authentication for the given user. This API must be used if the user loses access to their second factor auth device and has no recovery codes'
operationId: disable_user_2fa
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
message: 2FA disabled
'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'
web UI/REST API: add password reset In order to reset the password from the admin/client user interface, an SMTP configuration must be added and the user/admin must have an email address. You can prohibit the reset functionality on a per-user basis by using a specific restriction. Fixes #597
2021-11-13 12:25:43 +00:00
'/users/{username}/forgot-password':
parameters:
- name: username
in: path
description: the username
required: true
schema:
type: string
post:
security: []
tags:
- users
summary: Send a password reset code by email
description: 'You must configure an SMTP server, the account must have a valid email address and must not have the "reset-password-disabled" restriction, in which case SFTPGo will send a code via email to reset the password. If the specified user does not exist, the request will be silently ignored (a success response will be returned) to avoid disclosing existing users'
operationId: user_forgot_password
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'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
'/users/{username}/reset-password':
parameters:
- name: username
in: path
description: the username
required: true
schema:
type: string
post:
security: []
tags:
- users
summary: Reset the password
description: 'Set a new password using the code received via email'
operationId: user_reset_password
requestBody:
content:
application/json:
schema:
type: object
properties:
code:
type: string
password:
type: string
required: true
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'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
REST API: add a method to get the status of the services added a status page to the built-in web admin
2020-12-08 10:18:34 +00:00
/status:
get:
tags:
- maintenance
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
summary: Get status
improve OpenAPI schema so it is better rendered on Stoplight
2021-03-07 17:41:56 +00:00
description: Retrieves the status of the active services
REST API: add a method to get the status of the services added a status page to the built-in web admin
2020-12-08 10:18:34 +00:00
operationId: get_status
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
REST API: add a method to get the status of the services added a status page to the built-in web admin
2020-12-08 10:18:34 +00:00
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ServicesStatus'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'400':
REST API: add a method to get the status of the services added a status page to the built-in web admin
2020-12-08 10:18:34 +00:00
$ref: '#/components/responses/BadRequest'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
REST API: add a method to get the status of the services added a status page to the built-in web admin
2020-12-08 10:18:34 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API: add a method to get the status of the services added a status page to the built-in web admin
2020-12-08 10:18:34 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API: add a method to get the status of the services added a status page to the built-in web admin
2020-12-08 10:18:34 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
add backup/restore REST API
2019-12-27 22:12:44 +00:00
/dumpdata:
get:
tags:
document heathz endpoint
2020-11-01 09:39:10 +00:00
- maintenance
improve OpenAPI schema so it is better rendered on Stoplight
2021-03-07 17:41:56 +00:00
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'
add backup/restore REST API
2019-12-27 22:12:44 +00:00
operationId: dumpdata
parameters:
- in: query
web admin: add backup/restore
2021-01-22 18:42:18 +00:00
name: output-file
add backup/restore REST API
2019-12-27 22:12:44 +00:00
schema:
type: string
web admin: add backup/restore
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
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: |
extend virtual folders support to all storage backends Fixes #241
2021-03-21 18:15:47 +00:00
output data:
web admin: add backup/restore
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
memory provider: load users from a dump file The `memory` provider can load users from a dump obtained using the `dumpdata` REST API. This dump file can be configured using the dataprovider `name` configuration key. It will be loaded at startup and can be reloaded on demand using a `SIGHUP` on Unix based systems and a `paramchange` request to the running service on Windows. Fixes #66
2020-02-02 21:20:39 +00:00
- in: query
name: indent
schema:
type: integer
enum:
- 0
- 1
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: |
memory provider: load users from a dump file The `memory` provider can load users from a dump obtained using the `dumpdata` REST API. This dump file can be configured using the dataprovider `name` configuration key. It will be loaded at startup and can be reloaded on demand using a `SIGHUP` on Unix based systems and a `paramchange` request to the running service on Windows. Fixes #66
2020-02-02 21:20:39 +00:00
indent:
* `0` no indentation. This is the default
* `1` format the output JSON
add backup/restore REST API
2019-12-27 22:12:44 +00:00
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
add backup/restore REST API
2019-12-27 22:12:44 +00:00
description: successful operation
content:
application/json:
schema:
web admin: add backup/restore
2021-01-22 18:42:18 +00:00
oneOf:
- $ref: '#/components/schemas/ApiResponse'
- $ref: '#/components/schemas/BackupData'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'400':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/BadRequest'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
add backup/restore REST API
2019-12-27 22:12:44 +00:00
/loaddata:
web admin: add backup/restore
2021-01-22 18:42:18 +00:00
parameters:
- in: query
name: scan-quota
schema:
type: integer
enum:
- 0
- 1
- 2
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: |
web admin: add backup/restore
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
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: |
web admin: add backup/restore
2021-01-22 18:42:18 +00:00
Mode:
loaddata: improve shares restore usage and timestamps are now preserved
2021-11-27 10:12:51 +00:00
* `0` New objects are added, existing ones are updated. This is the default
* `1` New objects are added, existing ones are not modified
* `2` New objects are added, existing ones are updated and connected users are disconnected and so forced to use the new configuration
add backup/restore REST API
2019-12-27 22:12:44 +00:00
get:
tags:
document heathz endpoint
2020-11-01 09:39:10 +00:00
- maintenance
improve OpenAPI schema so it is better rendered on Stoplight
2021-03-07 17:41:56 +00:00
summary: Load data from path
loaddata: improve shares restore usage and timestamps are now preserved
2021-11-27 10:12:51 +00:00
description: 'Restores SFTPGo data from a JSON backup file on the server. Objects will be restored one by one and the restore is stopped if a object cannot be added or updated, so it could happen a partial restore'
web admin: add backup/restore
2021-01-22 18:42:18 +00:00
operationId: loaddata_from_file
add backup/restore REST API
2019-12-27 22:12:44 +00:00
parameters:
- in: query
web admin: add backup/restore
2021-01-22 18:42:18 +00:00
name: input-file
add backup/restore REST API
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
web admin: add backup/restore
2021-01-22 18:42:18 +00:00
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
web admin: add backup/restore
2021-01-22 18:42:18 +00:00
description: successful operation
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/ApiResponse'
web admin: add backup/restore
2021-01-22 18:42:18 +00:00
example:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
message: Data restored
'400':
web admin: add backup/restore
2021-01-22 18:42:18 +00:00
$ref: '#/components/responses/BadRequest'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
web admin: add backup/restore
2021-01-22 18:42:18 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
web admin: add backup/restore
2021-01-22 18:42:18 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
web admin: add backup/restore
2021-01-22 18:42:18 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
post:
tags:
- maintenance
improve OpenAPI schema so it is better rendered on Stoplight
2021-03-07 17:41:56 +00:00
summary: Load data
loaddata: improve shares restore usage and timestamps are now preserved
2021-11-27 10:12:51 +00:00
description: 'Restores SFTPGo data from a JSON backup. Objects will be restored one by one and the restore is stopped if a object cannot be added or updated, so it could happen a partial restore'
web admin: add backup/restore
2021-01-22 18:42:18 +00:00
operationId: loaddata_from_request_body
requestBody:
required: true
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/BackupData'
add backup/restore REST API
2019-12-27 22:12:44 +00:00
responses:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'200':
add backup/restore REST API
2019-12-27 22:12:44 +00:00
description: successful operation
content:
application/json:
schema:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/ApiResponse'
add backup/restore REST API
2019-12-27 22:12:44 +00:00
example:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
message: Data restored
'400':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/BadRequest'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'401':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Unauthorized'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'403':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/Forbidden'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
'500':
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
/user/changepwd:
put:
REST API: add support for API key authentication
2021-08-17 16:08:32 +00:00
security:
- BearerAuth: []
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
tags:
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- user APIs
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
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:
REST API: add support for API key authentication
2021-08-17 16:08:32 +00:00
security:
- BearerAuth: []
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
tags:
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- user APIs
rework user and admin profiles users and admins can now also update their email and description
2021-09-29 16:46:15 +00:00
deprecated: true
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
summary: Get the user's public keys
rework user and admin profiles users and admins can now also update their email and description
2021-09-29 16:46:15 +00:00
description: 'Returns the public keys for the logged in user. Deprecated please use "/user/profile" instead'
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
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:
REST API: add support for API key authentication
2021-08-17 16:08:32 +00:00
security:
- BearerAuth: []
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
tags:
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- user APIs
rework user and admin profiles users and admins can now also update their email and description
2021-09-29 16:46:15 +00:00
deprecated: true
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
summary: Set the user's public keys
rework user and admin profiles users and admins can now also update their email and description
2021-09-29 16:46:15 +00:00
description: 'Sets the public keys for the logged in user. Public keys must be in OpenSSH format. Deprecated please use "/user/profile" instead'
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
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'
rework user and admin profiles users and admins can now also update their email and description
2021-09-29 16:46:15 +00:00
/user/profile:
user: add a permission to disable changing api key authentication also implement the missing APIs to enable/disable api key authentication
2021-09-06 16:46:35 +00:00
get:
security:
- BearerAuth: []
tags:
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- user APIs
rework user and admin profiles users and admins can now also update their email and description
2021-09-29 16:46:15 +00:00
summary: Get user profile
description: 'Returns the profile for the logged in user'
operationId: get_user_profile
user: add a permission to disable changing api key authentication also implement the missing APIs to enable/disable api key authentication
2021-09-06 16:46:35 +00:00
responses:
'200':
description: successful operation
content:
application/json:
schema:
rework user and admin profiles users and admins can now also update their email and description
2021-09-29 16:46:15 +00:00
$ref: '#/components/schemas/UserProfile'
user: add a permission to disable changing api key authentication also implement the missing APIs to enable/disable api key authentication
2021-09-06 16:46:35 +00:00
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
put:
security:
- BearerAuth: []
tags:
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- user APIs
web UI: update js and css deps
2021-09-30 08:23:25 +00:00
summary: Update user profile
rework user and admin profiles users and admins can now also update their email and description
2021-09-29 16:46:15 +00:00
description: 'Allows to update the profile for the logged in user'
operationId: update_user_profile
user: add a permission to disable changing api key authentication also implement the missing APIs to enable/disable api key authentication
2021-09-06 16:46:35 +00:00
requestBody:
required: true
content:
application/json:
schema:
rework user and admin profiles users and admins can now also update their email and description
2021-09-29 16:46:15 +00:00
$ref: '#/components/schemas/UserProfile'
user: add a permission to disable changing api key authentication also implement the missing APIs to enable/disable api key authentication
2021-09-06 16:46:35 +00:00
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'
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
/user/2fa/recoverycodes:
get:
security:
- BearerAuth: []
tags:
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- user APIs
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
summary: Get recovery codes
description: 'Returns the recovery codes for the logged in user. Recovery codes can be used if the user loses access to their second factor auth device. Recovery codes are returned unencrypted'
operationId: get_user_recovery_codes
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RecoveryCode'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
post:
security:
- BearerAuth: []
tags:
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- user APIs
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
summary: Generate recovery codes
description: 'Generates new recovery codes for the logged in user. Generating new recovery codes you automatically invalidate old ones'
operationId: generate_user_recovery_codes
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'
/user/totp/configs:
get:
security:
- BearerAuth: []
tags:
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- user APIs
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
summary: Get available TOTP configuration
description: Returns the available TOTP configurations for the logged in user
operationId: get_user_totp_configs
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TOTPConfig'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/user/totp/generate:
post:
security:
- BearerAuth: []
tags:
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- user APIs
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
summary: Generate a new TOTP secret
description: 'Generates a new TOTP secret, including the QR code as png, using the specified configuration for the logged in user'
operationId: generate_user_totp_secret
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
config_name:
type: string
description: 'name of the configuration to use to generate the secret'
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: object
properties:
config_name:
type: string
issuer:
type: string
secret:
type: string
qr_code:
type: string
format: byte
description: 'QR code png encoded as BASE64'
'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/totp/validate:
post:
security:
- BearerAuth: []
tags:
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- user APIs
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
summary: Validate a one time authentication code
description: 'Checks if the given authentication code can be validated using the specified secret and config name'
operationId: validate_user_totp_secret
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
config_name:
type: string
description: 'name of the configuration to use to validate the passcode'
passcode:
type: string
description: 'passcode to validate'
secret:
type: string
description: 'secret to use to validate the passcode'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
message: Passcode successfully validated
'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/totp/save:
post:
security:
- BearerAuth: []
tags:
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- user APIs
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
summary: Save a TOTP config
description: 'Saves the specified TOTP config for the logged in user'
operationId: save_user_totp_config
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserTOTPConfig'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
message: TOTP configuration saved
'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'
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
/user/shares:
get:
tags:
- user APIs
summary: List user shares
description: Returns the share for the logged in user
operationId: get_user_shares
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 shares by ID. 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/Share'
'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:
- user APIs
summary: Add a share
operationId: add_share
description: 'Adds a new share. The share id will be auto-generated'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Share'
responses:
'201':
description: successful operation
headers:
X-Object-ID:
schema:
type: string
description: ID for the new created share
Location:
schema:
type: string
description: URL to retrieve the details for the new created share
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/shares/{id}':
parameters:
- name: id
in: path
description: the share id
required: true
schema:
type: string
get:
tags:
- user APIs
summary: Get share by id
description: Returns a share by id for the logged in user
operationId: get_user_share_by_id
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Share'
'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:
- user APIs
summary: Update share
description: 'Updates an existing share belonging to the logged in user'
operationId: update_user_share
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Share'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
message: Share 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:
- user APIs
summary: Delete share
description: 'Deletes an existing share belonging to the logged in user'
operationId: delete_user_share
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
example:
message: Share 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'
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
/user/folder:
get:
tags:
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- user APIs
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
summary: Read folders contents
web UI: add support for upload, create dirs, rename, delete
2021-07-26 18:55:49 +00:00
description: Returns the contents of the specified folder for the logged in user. Please use '/user/dirs' instead
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
operationId: get_user_folder_contents
web UI: add support for upload, create dirs, rename, delete
2021-07-26 18:55:49 +00:00
deprecated: true
parameters:
- in: query
name: path
add support for a start directory Fixes #705 Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-03-03 11:44:56 +00:00
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 user's start directory is assumed. If relative, the user's start directory is used as the base
web UI: add support for upload, create dirs, rename, delete
2021-07-26 18:55:49 +00:00
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/dirs:
get:
tags:
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- user APIs
web UI: add support for upload, create dirs, rename, delete
2021-07-26 18:55:49 +00:00
summary: Read directory contents
description: Returns the contents of the specified directory for the logged in user
operationId: get_user_dir_contents
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
parameters:
- in: query
name: path
add support for a start directory Fixes #705 Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-03-03 11:44:56 +00:00
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 user's start directory is assumed. If relative, the user's start directory is used as the base
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
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'
users API: add API to create, delete, rename files and directories
2021-07-23 08:19:27 +00:00
post:
tags:
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- user APIs
users API: add API to create, delete, rename files and directories
2021-07-23 08:19:27 +00:00
summary: Create a directory
description: Create a directory for the logged in user
web UI: add support for upload, create dirs, rename, delete
2021-07-26 18:55:49 +00:00
operationId: create_user_dir
users API: add API to create, delete, rename files and directories
2021-07-23 08:19:27 +00:00
parameters:
- in: query
name: path
description: Path to the folder to create. It must be URL encoded, for example the path "my dir/àdir" must be sent as "my%20dir%2F%C3%A0dir"
schema:
type: string
required: true
REST API: add an option to create missing dirs
2021-12-19 11:14:53 +00:00
- in: query
name: mkdir_parents
description: Create parent directories if they do not exist?
schema:
type: boolean
required: false
users API: add API to create, delete, rename files and directories
2021-07-23 08:19:27 +00:00
responses:
'201':
description: successful operation
content:
application/json:
schema:
type: array
items:
$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'
patch:
tags:
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- user APIs
users API: add API to create, delete, rename files and directories
2021-07-23 08:19:27 +00:00
summary: Rename a directory
add separate permissions to delete and rename files and dirs perm_delete and perm_rename still exist for backward compatibility, now they are an alias to assign both new split permissions
2021-11-14 15:23:33 +00:00
description: Rename a directory for the logged in user. The rename is allowed for empty directory or for non empty local directories, with no virtual folders inside
web UI: add support for upload, create dirs, rename, delete
2021-07-26 18:55:49 +00:00
operationId: rename_user_dir
users API: add API to create, delete, rename files and directories
2021-07-23 08:19:27 +00:00
parameters:
- in: query
name: path
description: Path to the folder to rename. It must be URL encoded, for example the path "my dir/àdir" must be sent as "my%20dir%2F%C3%A0dir"
schema:
type: string
required: true
- in: query
name: target
description: New name. It must be URL encoded, for example the path "my dir/àdir" must be sent as "my%20dir%2F%C3%A0dir"
schema:
type: string
required: true
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$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'
delete:
tags:
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- user APIs
users API: add API to create, delete, rename files and directories
2021-07-23 08:19:27 +00:00
summary: Delete a directory
description: Delete a directory for the logged in user. Only empty directories can be deleted
web UI: add support for upload, create dirs, rename, delete
2021-07-26 18:55:49 +00:00
operationId: delete_user_dir
users API: add API to create, delete, rename files and directories
2021-07-23 08:19:27 +00:00
parameters:
- in: query
name: path
description: Path to the folder to delete. It must be URL encoded, for example the path "my dir/àdir" must be sent as "my%20dir%2F%C3%A0dir"
schema:
type: string
required: true
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$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'
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
/user/file:
get:
tags:
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- user APIs
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
summary: Download a single file
web UI: add support for upload, create dirs, rename, delete
2021-07-26 18:55:49 +00:00
description: Returns the file contents as response body. Please use '/user/files' instead
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
operationId: get_user_file
web UI: add support for upload, create dirs, rename, delete
2021-07-26 18:55:49 +00:00
deprecated: true
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/files:
get:
tags:
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- user APIs
web UI: add support for upload, create dirs, rename, delete
2021-07-26 18:55:49 +00:00
summary: Download a single file
description: Returns the file contents as response body
operationId: download_user_file
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
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
web client: allow to preview images and pdf pdf depends on browser support. It does not work on mobile devices.
2021-11-25 18:24:32 +00:00
- in: query
name: inline
required: false
description: 'If set, the response will not have the Content-Disposition header set to `attachment`'
schema:
type: string
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
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'
users API: add API to create, delete, rename files and directories
2021-07-23 08:19:27 +00:00
post:
tags:
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- user APIs
users API: add API to create, delete, rename files and directories
2021-07-23 08:19:27 +00:00
summary: Upload files
description: Upload one or more files for the logged in user
operationId: create_user_files
parameters:
- in: query
name: path
description: Parent directory for the uploaded files. 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 path is assumed. If a file with the same name already exists, it will be overwritten
schema:
type: string
REST API: add an option to create missing dirs
2021-12-19 11:14:53 +00:00
- in: query
name: mkdir_parents
description: Create parent directories if they do not exist?
schema:
type: boolean
required: false
users API: add API to create, delete, rename files and directories
2021-07-23 08:19:27 +00:00
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
filenames:
users API: add API to create, delete, rename files and directories
2021-07-23 08:19:27 +00:00
type: array
items:
type: string
format: binary
minItems: 1
uniqueItems: true
required: true
responses:
'201':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ApiResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
web client: improve file upload
2021-11-22 11:25:36 +00:00
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
users API: add API to create, delete, rename files and directories
2021-07-23 08:19:27 +00:00
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
patch:
tags:
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- user APIs
Add a link on the login pages to switch between admin and web client login The links are hidden if only the web admin or only thw web client is enabled and can also be controlled using the "hide_login_url" setting Fixes #485
2021-07-27 16:43:00 +00:00
summary: Rename a file
users API: add API to create, delete, rename files and directories
2021-07-23 08:19:27 +00:00
description: Rename a file for the logged in user
operationId: rename_user_file
parameters:
- in: query
name: path
description: Path to the file to rename. It must be URL encoded
schema:
type: string
required: true
- in: query
name: target
description: New name. It must be URL encoded
schema:
type: string
required: true
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$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'
delete:
tags:
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- user APIs
users API: add API to create, delete, rename files and directories
2021-07-23 08:19:27 +00:00
summary: Delete a file
description: Delete a file for the logged in user.
operationId: delete_user_file
parameters:
- in: query
name: path
description: Path to the file to delete. It must be URL encoded
schema:
type: string
required: true
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$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'
web client: use fetch to upload files also add REST API to upload a single file as POST body
2021-12-08 18:25:22 +00:00
/user/files/upload:
post:
tags:
- user APIs
summary: Upload a single file
description: 'Upload a single file for the logged in user to an existing directory. This API does not use multipart/form-data and so no temporary files are created server side but only a single file can be uploaded as POST body'
operationId: create_user_file
parameters:
- in: query
name: path
description: Full file path. It must be path encoded, for example the path "my dir/àdir/file.txt" must be sent as "my%20dir%2F%C3%A0dir%2Ffile.txt". The parent directory must exist. If a file with the same name already exists, it will be overwritten
schema:
type: string
required: true
REST API: add an option to create missing dirs
2021-12-19 11:14:53 +00:00
- in: query
name: mkdir_parents
description: Create parent directories if they do not exist?
schema:
type: boolean
required: false
web client: use fetch to upload files also add REST API to upload a single file as POST body
2021-12-08 18:25:22 +00:00
- in: header
name: X-SFTPGO-MTIME
schema:
type: integer
description: File modification time as unix timestamp in milliseconds
requestBody:
content:
application/*:
schema:
type: string
format: binary
text/*:
schema:
type: string
format: binary
image/*:
schema:
type: string
format: binary
audio/*:
schema:
type: string
format: binary
video/*:
schema:
type: string
format: binary
required: true
responses:
'201':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ApiResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/user/files/metadata:
patch:
tags:
- user APIs
summary: Set metadata for a file/directory
description: 'Set supported metadata attributes for the specified file or directory'
operationId: setprops_user_file
parameters:
- in: query
name: path
description: Full file/directory path. 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
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
modification_time:
type: integer
description: File modification time as unix timestamp in milliseconds
required: true
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ApiResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'413':
$ref: '#/components/responses/RequestEntityTooLarge'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
/user/streamzip:
post:
tags:
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- user APIs
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
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'
first version
2019-07-20 10:26:52 +00:00
components:
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
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:
web client: improve file upload
2021-11-22 11:25:36 +00:00
schema:
$ref: '#/components/schemas/ApiResponse'
RequestEntityTooLarge:
description: Request Entity Too Large, max allowed size exceeded
content:
application/json:
REST API: remove status from ApiResponse it duplicates the header HTTP status
2020-09-08 07:45:21 +00:00
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'
first version
2019-07-20 10:26:52 +00:00
schemas:
Permission:
type: string
enum:
- '*'
- list
- download
- upload
add a new permission for overwriting existing files The upload permission is required to allow file overwrite
2019-09-17 06:53:45 +00:00
- overwrite
first version
2019-07-20 10:26:52 +00:00
- delete
add separate permissions to delete and rename files and dirs perm_delete and perm_rename still exist for backward compatibility, now they are an alias to assign both new split permissions
2021-11-14 15:23:33 +00:00
- delete_files
- delete_dirs
first version
2019-07-20 10:26:52 +00:00
- rename
add separate permissions to delete and rename files and dirs perm_delete and perm_rename still exist for backward compatibility, now they are an alias to assign both new split permissions
2021-11-14 15:23:33 +00:00
- rename_files
- rename_dirs
first version
2019-07-20 10:26:52 +00:00
- create_dirs
- create_symlinks
sftpd: add support for chmod/chown added matching permissions too and a new setting "setstat_mode". Setting setstat_mode to 1 you can keep the previous behaviour that silently ignore setstat requests
2019-11-15 11:15:07 +00:00
- chmod
- chown
sftpd: add support for chtimes This improve rclone compatibility
2019-11-16 09:23:41 +00:00
- chtimes
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: |
first version
2019-07-20 10:26:52 +00:00
Permissions:
set version to 0.9.2
2019-09-18 20:19:34 +00:00
* `*` - all permissions are granted
first version
2019-07-20 10:26:52 +00:00
* `list` - list items is allowed
* `download` - download files is allowed
* `upload` - upload files is allowed
add a new permission for overwriting existing files The upload permission is required to allow file overwrite
2019-09-17 06:53:45 +00:00
* `overwrite` - overwrite an existing file, while uploading, is allowed. upload permission is required to allow file overwrite
first version
2019-07-20 10:26:52 +00:00
* `delete` - delete files or directories is allowed
add separate permissions to delete and rename files and dirs perm_delete and perm_rename still exist for backward compatibility, now they are an alias to assign both new split permissions
2021-11-14 15:23:33 +00:00
* `delete_files` - delete files is allowed
* `delete_dirs` - delete directories is allowed
first version
2019-07-20 10:26:52 +00:00
* `rename` - rename files or directories is allowed
add separate permissions to delete and rename files and dirs perm_delete and perm_rename still exist for backward compatibility, now they are an alias to assign both new split permissions
2021-11-14 15:23:33 +00:00
* `rename_files` - rename files is allowed
* `rename_dirs` - rename directories is allowed
first version
2019-07-20 10:26:52 +00:00
* `create_dirs` - create directories is allowed
* `create_symlinks` - create links is allowed
sftpd: add support for chmod/chown added matching permissions too and a new setting "setstat_mode". Setting setstat_mode to 1 you can keep the previous behaviour that silently ignore setstat requests
2019-11-15 11:15:07 +00:00
* `chmod` changing file or directory permissions is allowed
* `chown` changing file or directory owner and group is allowed
sftpd: add support for chtimes This improve rclone compatibility
2019-11-16 09:23:41 +00:00
* `chtimes` changing file or directory access and modification time is allowed
add per directory permissions we can now have permissions such as these ones {"/":["*"],"/somedir":["list","download"]} The old permissions are automatically converted to the new structure, no database migration is needed
2019-12-25 17:20:19 +00:00
DirPermissions:
type: object
additionalProperties:
type: array
items:
$ref: '#/components/schemas/Permission'
minItems: 1
minProperties: 1
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
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'
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
AdminPermissions:
type: string
enum:
- '*'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
- add_users
- edit_users
- del_users
- view_users
- view_conns
- close_conns
- view_status
- manage_admins
REST API: add support for API key authentication
2021-08-17 16:08:32 +00:00
- manage_apikeys
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
- quota_scans
- manage_system
- manage_defender
- view_defender
add basic REST APIs for data retention Fixes #495
2021-09-25 10:20:31 +00:00
- retention_checks
add support for metadata plugins
2021-12-16 17:18:36 +00:00
- metadata_checks
REST API: add events search
2021-10-23 13:47:21 +00:00
- view_events
extend virtual folders support to all storage backends Fixes #241
2021-03-21 18:15:47 +00:00
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
REST API: add support for API key authentication
2021-08-17 16:08:32 +00:00
* `manage_apikeys` - manage API keys is allowed
add basic REST APIs for data retention Fixes #495
2021-09-25 10:20:31 +00:00
* `quota_scans` - view and start quota scans is allowed
* `manage_system` - backups and restores are allowed
extend virtual folders support to all storage backends Fixes #241
2021-03-21 18:15:47 +00:00
* `manage_defender` - remove ip from the dynamic blocklist is allowed
* `view_defender` - list the dynamic blocklist is allowed
add basic REST APIs for data retention Fixes #495
2021-09-25 10:20:31 +00:00
* `retention_checks` - view and start retention checks is allowed
add support for metadata plugins
2021-12-16 17:18:36 +00:00
* `metadata_checks` - view and start metadata checks is allowed
REST API: add events search
2021-10-23 13:47:21 +00:00
* `view_events` - view and search filesystem and provider events is allowed
eventsearcher plugin: add support to search for provider, bucket, endpoint Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-01-03 16:02:52 +00:00
FsProviders:
type: integer
enum:
- 0
- 1
- 2
- 3
- 4
- 5
description: |
Filesystem providers:
* `0` - Local filesystem
* `1` - S3 Compatible Object Storage
* `2` - Google Cloud Storage
* `3` - Azure Blob Storage
* `4` - Local filesystem encrypted
* `5` - SFTP
add support for per user authentication methods You can, for example, deny one or more authentication methods to one or more users.
2020-02-19 21:39:30 +00:00
LoginMethods:
type: string
enum:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
- publickey
- password
allow to require two-factor auth for users Fixes #721 Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-03-06 15:57:13 +00:00
- password-over-SSH
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
- keyboard-interactive
- publickey+password
- publickey+keyboard-interactive
- TLSCertificate
- TLSCertificate+password
description: |
extend virtual folders support to all storage backends Fixes #241
2021-03-21 18:15:47 +00:00
Available login methods. To enable multi-step authentication you have to allow only multi-step login methods
* `publickey`
allow to require two-factor auth for users Fixes #721 Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-03-06 15:57:13 +00:00
* `password`, password for all the supported protocols
* `password-over-SSH`, password over SSH protocol (SSH/SFTP/SCP)
extend virtual folders support to all storage backends Fixes #241
2021-03-21 18:15:47 +00:00
* `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
Allow individual protocols to be enabled per user Fixes #154
2020-08-17 10:49:20 +00:00
SupportedProtocols:
type: string
enum:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
- SSH
- FTP
- DAV
add a basic front-end web interface for end-users Fixes #339 #321 #398
2021-05-06 19:35:43 +00:00
- HTTP
extend virtual folders support to all storage backends Fixes #241
2021-03-21 18:15:47 +00:00
description: |
Protocols:
* `SSH` - includes both SFTP and SSH commands
* `FTP` - plain FTP and FTPES/FTPS
* `DAV` - WebDAV over HTTP/HTTPS
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
* `HTTP` - WebClient/REST API
MFAProtocols:
type: string
enum:
- SSH
- FTP
- HTTP
description: |
Protocols:
* `SSH` - includes both SFTP and SSH commands
* `FTP` - plain FTP and FTPES/FTPS
* `HTTP` - WebClient/REST API
plugins: improve notifier and searcher
2021-10-20 17:39:49 +00:00
EventProtocols:
type: string
enum:
- SSH
- SFTP
- SCP
- FTP
- DAV
- HTTP
shares: add permission to deny sharing without password Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-02-19 12:31:58 +00:00
- HTTPShare
plugins: improve notifier and searcher
2021-10-20 17:39:49 +00:00
- DataRetention
OIDC: execute pre-login hook after IDP authentication so the SFTPGo users can be auto-created using the hook Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-02-19 09:53:35 +00:00
- OIDC
plugins: improve notifier and searcher
2021-10-20 17:39:49 +00:00
description: |
Protocols:
* `SSH` - SSH commands
* `SFTP` - SFTP protocol
* `FTP` - plain FTP and FTPES/FTPS
* `DAV` - WebDAV
* `HTTP` - WebClient/REST API
shares: add permission to deny sharing without password Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-02-19 12:31:58 +00:00
* `HTTPShare` - the event is generated in a public share
plugins: improve notifier and searcher
2021-10-20 17:39:49 +00:00
* `DataRetention` - the event is generated by a data retention check
OIDC: execute pre-login hook after IDP authentication so the SFTPGo users can be auto-created using the hook Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-02-19 09:53:35 +00:00
* `OIDC` - OpenID Connect
add a basic front-end web interface for end-users Fixes #339 #321 #398
2021-05-06 19:35:43 +00:00
WebClientOptions:
type: string
enum:
- publickey-change-disabled
user API: allow to disable writes ... ... even if the user has permissions for these actions
2021-07-23 19:41:02 +00:00
- write-disabled
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
- mfa-disabled
web client UI: add a permission to disable password change Fixes #528
2021-09-05 16:49:13 +00:00
- password-change-disabled
user: add a permission to disable changing api key authentication also implement the missing APIs to enable/disable api key authentication
2021-09-06 16:46:35 +00:00
- api-key-auth-change-disabled
rework user and admin profiles users and admins can now also update their email and description
2021-09-29 16:46:15 +00:00
- info-change-disabled
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- shares-disabled
web UI/REST API: add password reset In order to reset the password from the admin/client user interface, an SMTP configuration must be added and the user/admin must have an email address. You can prohibit the reset functionality on a per-user basis by using a specific restriction. Fixes #597
2021-11-13 12:25:43 +00:00
- password-reset-disabled
shares: add permission to deny sharing without password Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-02-19 12:31:58 +00:00
- shares-without-password-disabled
add a basic front-end web interface for end-users Fixes #339 #321 #398
2021-05-06 19:35:43 +00:00
description: |
Options:
* `publickey-change-disabled` - changing SSH public keys is not allowed
user API: allow to disable writes ... ... even if the user has permissions for these actions
2021-07-23 19:41:02 +00:00
* `write-disabled` - upload, rename, delete are not allowed even if the user has permissions for these actions
web client UI: add a permission to disable password change Fixes #528
2021-09-05 16:49:13 +00:00
* `mfa-disabled` - enabling multi-factor authentication is not allowed. This option cannot be set if the user has MFA already enabled
* `password-change-disabled` - changing password is not allowed
user: add a permission to disable changing api key authentication also implement the missing APIs to enable/disable api key authentication
2021-09-06 16:46:35 +00:00
* `api-key-auth-change-disabled` - enabling/disabling API key authentication is not allowed
rework user and admin profiles users and admins can now also update their email and description
2021-09-29 16:46:15 +00:00
* `info-change-disabled` - changing info such as email and description is not allowed
shares: add permission to deny sharing without password Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-02-19 12:31:58 +00:00
* `shares-disabled` - sharing files and directories with external users is not allowed
* `password-reset-disabled` - resetting the password is not allowed
* `shares-without-password-disabled` - creating shares without password protection is not allowed
data retention: allow to notify results via e-mail
2021-10-02 20:25:41 +00:00
RetentionCheckNotification:
type: string
enum:
add data retention check hook
2021-10-03 13:17:49 +00:00
- Hook
data retention: allow to notify results via e-mail
2021-10-02 20:25:41 +00:00
- Email
description: |
Options:
add data retention check hook
2021-10-03 13:17:49 +00:00
* `Hook` - notify result using the defined hook. A "data_retention_hook" must be defined in your configuration file for this to work
data retention: allow to notify results via e-mail
2021-10-02 20:25:41 +00:00
* `Email` - notify results by email. The admin starting the retention check must have an associated email address and the SMTP server must be configured for this to work
REST API: add support for API key authentication
2021-08-17 16:08:32 +00:00
APIKeyScope:
type: integer
enum:
- 1
- 2
description: |
Options:
* `1` - admin scope. The API key will be used to impersonate an SFTPGo admin
* `2` - user scope. The API key will be used to impersonate an SFTPGo user
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
ShareScope:
type: integer
enum:
- 1
- 2
description: |
Options:
* `1` - read scope
* `2` - write scope
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
TOTPHMacAlgo:
type: string
enum:
- sha1
- sha256
- sha512
description: 'Supported HMAC algorithms for Time-based one time passwords'
UserType:
type: string
enum:
- ''
- LDAPUser
- OSUser
description: This is an hint for authentication plugins. It is ignored when using SFTPGo internal authentication
plugins: improve notifier and searcher
2021-10-20 17:39:49 +00:00
FsEventStatus:
type: integer
enum:
- 1
- 2
- 3
description: >
Event status:
* `1` - no error
* `2` - generic error
* `3` - quota exceeded error
FsEventAction:
type: string
enum:
- download
eventsearcher plugin: add support to search for provider, bucket, endpoint Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-01-03 16:02:52 +00:00
- pre-upload
plugins: improve notifier and searcher
2021-10-20 17:39:49 +00:00
- upload
- delete
- rename
- mkdir
- rmdir
- ssh_cmd
ProviderEventAction:
type: string
enum:
- add
- update
- delete
ProviderEventObjectType:
type: string
enum:
- user
- admin
- api_key
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
- share
add more details to the server status page add all supported fields to the OpenAPI docs Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-02-26 15:43:29 +00:00
SSHAuthentications:
type: string
enum:
- publickey
- password
- keyboard-interactive
- publickey+password
- publickey+keyboard-interactive
TLSVersions:
type: integer
enum:
- 12
- 13
description: >
TLS version:
* `12` - TLS 1.2
* `13` - TLS 1.3
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
TOTPConfig:
type: object
properties:
name:
type: string
issuer:
type: string
algo:
$ref: '#/components/schemas/TOTPHMacAlgo'
RecoveryCode:
type: object
properties:
secret:
$ref: '#/components/schemas/Secret'
used:
type: boolean
description: 'Recovery codes to use if the user loses access to their second factor auth device. Each code can only be used once, you should use these codes to login and disable or reset 2FA for your account'
BaseTOTPConfig:
type: object
properties:
enabled:
type: boolean
config_name:
type: string
description: 'This name must be defined within the "totp" section of the SFTPGo configuration file. You will be unable to save a user/admin referencing a missing config_name'
secret:
$ref: '#/components/schemas/Secret'
AdminTOTPConfig:
allOf:
- $ref: '#/components/schemas/BaseTOTPConfig'
UserTOTPConfig:
allOf:
- $ref: '#/components/schemas/BaseTOTPConfig'
- type: object
properties:
protocols:
type: array
items:
$ref: '#/components/schemas/MFAProtocols'
description: 'TOTP will be required for the specified protocols. SSH protocol (SFTP/SCP/SSH commands) will ask for the TOTP passcode if the client uses keyboard interactive authentication. FTP has no standard way to support two factor authentication, if you enable the FTP support, you have to add the TOTP passcode after the password. For example if your password is "password" and your one time passcode is "123456" you have to use "password123456" as password. WebDAV is not supported since each single request must be authenticated and a passcode cannot be reused.'
add support for limit files using shell like patterns Fixes #209
2020-11-15 21:04:48 +00:00
PatternsFilter:
type: object
properties:
path:
type: string
add basic REST APIs for data retention Fixes #495
2021-09-25 10:20:31 +00:00
description: 'exposed virtual path, if no other specific filter is defined, the filter applies 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'
add support for limit files using shell like patterns Fixes #209
2020-11-15 21:04:48 +00:00
allowed_patterns:
type: array
items:
type: string
add hide policy to pattern filters Disallowed files/dirs can be completly hidden. This may cause performance issues for large directories Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-01-15 16:16:49 +00:00
description: 'list of, case insensitive, allowed shell like patterns.'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
example:
- '*.jpg'
- a*b?.png
add support for limit files using shell like patterns Fixes #209
2020-11-15 21:04:48 +00:00
denied_patterns:
type: array
items:
type: string
add hide policy to pattern filters Disallowed files/dirs can be completly hidden. This may cause performance issues for large directories Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-01-15 16:16:49 +00:00
description: 'list of, case insensitive, denied shell like patterns. Denied patterns are evaluated before the allowed ones'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
example:
- '*.zip'
add hide policy to pattern filters Disallowed files/dirs can be completly hidden. This may cause performance issues for large directories Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-01-15 16:16:49 +00:00
deny_policy:
type: integer
enum:
- 0
- 1
description: |
Deny policies
* `0` - default policy. Denied files/directories matching the filters are visible in directory listing but cannot be uploaded/downloaded/overwritten/renamed
* `1` - deny policy hide. This policy applies the same restrictions as the default one and denied files/directories matching the filters will also be hidden in directory listing. This mode may cause performance issues for large directories
allow to disable some hooks on a per-user basis This way you can, for example, mix external and internal users
2021-04-04 20:32:25 +00:00
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
add support for different bandwidth limits based on client IP
2021-12-10 17:43:26 +00:00
BandwidthLimit:
type: object
properties:
sources:
type: array
items:
type: string
description: 'Source networks in CIDR notation as defined in RFC 4632 and RFC 4291 for example `192.0.2.0/24` or `2001:db8::/32`. The limit applies if the defined networks contain the client IP'
upload_bandwidth:
type: integer
format: int32
description: 'Maximum upload bandwidth as KB/s, 0 means unlimited'
download_bandwidth:
type: integer
format: int32
description: 'Maximum download bandwidth as KB/s, 0 means unlimited'
add support for data transfer bandwidth limits with total limit or separate settings for uploads and downloads and overrides based on the client's IP address. Limits can be reset using the REST API Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-01-30 10:42:36 +00:00
DataTransferLimit:
type: object
properties:
sources:
type: array
items:
type: string
description: 'Source networks in CIDR notation as defined in RFC 4632 and RFC 4291 for example `192.0.2.0/24` or `2001:db8::/32`. The limit applies if the defined networks contain the client IP'
upload_data_transfer:
type: integer
description: 'Maximum data transfer allowed for uploads as MB. 0 means no limit'
download_data_transfer:
type: integer
description: 'Maximum data transfer allowed for downloads as MB. 0 means no limit'
total_data_transfer:
type: integer
description: 'Maximum total data transfer as MB. 0 means unlimited. You can set a total data transfer instead of the individual values for uploads and downloads'
add groups support Using groups simplifies the administration of multiple accounts by letting you assign settings once to a group, instead of multiple times to each individual user. Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-04-25 13:49:11 +00:00
BaseUserFilters:
Add support for allowed/denied IP/Mask Login can be restricted to specific ranges of IP address or to a specific IP address. Please apply the appropriate SQL upgrade script to add the filter field to your database. The filter database field will allow to add other filters without requiring a new database migration
2019-12-30 17:37:50 +00:00
type: object
properties:
allowed_ip:
type: array
items:
type: string
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
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'
Add support for allowed/denied IP/Mask Login can be restricted to specific ranges of IP address or to a specific IP address. Please apply the appropriate SQL upgrade script to add the filter field to your database. The filter database field will allow to add other filters without requiring a new database migration
2019-12-30 17:37:50 +00:00
denied_ip:
type: array
items:
type: string
description: clients connecting from these IP/Mask are not allowed. Denied rules are evaluated before allowed ones
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
example:
- 172.16.0.0/16
add support for per user authentication methods You can, for example, deny one or more authentication methods to one or more users.
2020-02-19 21:39:30 +00:00
denied_login_methods:
type: array
items:
$ref: '#/components/schemas/LoginMethods'
description: if null or empty any available login method is allowed
Allow individual protocols to be enabled per user Fixes #154
2020-08-17 10:49:20 +00:00
denied_protocols:
type: array
items:
$ref: '#/components/schemas/SupportedProtocols'
description: if null or empty any available protocol is allowed
add support for limit files using shell like patterns Fixes #209
2020-11-15 21:04:48 +00:00
file_patterns:
type: array
items:
$ref: '#/components/schemas/PatternsFilter'
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
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'
add a maximum allowed size for a single upload
2020-08-16 18:17:02 +00:00
max_upload_file_size:
type: integer
format: int64
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
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`'
FTP: improve TLS certificate authentication For each user you can now configure: - TLS certificate auth - TLS certificate auth and password - Password auth For TLS auth, the certificate common name must match the name provided using the "USER" FTP command
2021-02-28 11:10:40 +00:00
tls_username:
type: string
enum:
- None
- CommonName
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
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'
allow to disable some hooks on a per-user basis This way you can, for example, mix external and internal users
2021-04-04 20:32:25 +00:00
hooks:
$ref: '#/components/schemas/HooksFilter'
allow to disable login filesystem checks 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.
2021-04-05 15:57:30 +00:00
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
add a basic front-end web interface for end-users Fixes #339 #321 #398
2021-05-06 19:35:43 +00:00
web_client:
type: array
items:
$ref: '#/components/schemas/WebClientOptions'
user API: allow to disable writes ... ... even if the user has permissions for these actions
2021-07-23 19:41:02 +00:00
description: WebClient/user REST API related configuration options
REST API: add support for API key authentication
2021-08-17 16:08:32 +00:00
allow_api_key_auth:
type: boolean
description: 'API key authentication allows to impersonate this user with an API key'
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
user_type:
$ref: '#/components/schemas/UserType'
add support for different bandwidth limits based on client IP
2021-12-10 17:43:26 +00:00
bandwidth_limits:
type: array
items:
$ref: '#/components/schemas/BandwidthLimit'
add support for data transfer bandwidth limits with total limit or separate settings for uploads and downloads and overrides based on the client's IP address. Limits can be reset using the REST API Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-01-30 10:42:36 +00:00
data_transfer_limits:
type: array
items:
$ref: '#/components/schemas/DataTransferLimit'
allow to cache external authentications Fixes #733 Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-02-25 10:51:10 +00:00
external_auth_cache_time:
type: integer
description: 'Defines the cache time, in seconds, for users authenticated using an external auth hook. 0 means no cache'
add support for a start directory Fixes #705 Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-03-03 11:44:56 +00:00
start_directory:
type: string
description: 'Specifies an alternate starting directory. If not set, the default is "/". This option is supported for SFTP/SCP, FTP and HTTP (WebClient/REST API) protocols. Relative paths will use this directory as base.'
allow to require two-factor auth for users Fixes #721 Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-03-06 15:57:13 +00:00
2fa_protocols:
type: array
items:
$ref: '#/components/schemas/MFAProtocols'
description: 'Defines protocols that require two factor authentication'
add a basic front-end web interface for end-users Fixes #339 #321 #398
2021-05-06 19:35:43 +00:00
description: Additional user options
add groups support Using groups simplifies the administration of multiple accounts by letting you assign settings once to a group, instead of multiple times to each individual user. Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-04-25 13:49:11 +00:00
UserFilters:
allOf:
- $ref: '#/components/schemas/BaseUserFilters'
- type: object
properties:
totp_config:
$ref: '#/components/schemas/UserTOTPConfig'
recovery_codes:
type: array
items:
$ref: '#/components/schemas/RecoveryCode'
add a dedicated struct to store encrypted credentials also gcs credentials are now encrypted, both on disk and inside the provider. Data provider is automatically migrated and load data will accept old format too but you should upgrade to the new format to avoid future issues
2020-11-22 20:53:04 +00:00
Secret:
type: object
properties:
status:
type: string
enum:
- Plain
- AES-256-GCM
add KMS support Fixes #226
2020-11-30 20:46:34 +00:00
- Secretbox
- GCP
- AWS
- VaultTransit
add basic REST APIs for data retention Fixes #495
2021-09-25 10:20:31 +00:00
- AzureKeyVault
add a dedicated struct to store encrypted credentials also gcs credentials are now encrypted, both on disk and inside the provider. Data provider is automatically migrated and load data will accept old format too but you should upgrade to the new format to avoid future issues
2020-11-22 20:53:04 +00:00
- Redacted
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: 'Set to "Plain" to add or update an existing secret, set to "Redacted" to preserve the existing value'
add a dedicated struct to store encrypted credentials also gcs credentials are now encrypted, both on disk and inside the provider. Data provider is automatically migrated and load data will accept old format too but you should upgrade to the new format to avoid future issues
2020-11-22 20:53:04 +00:00
payload:
type: string
key:
type: string
additional_data:
type: string
kms: remember if a secret was saved without a master key So we will be able to decrypt secret stored without a master key if a such key is provided later
2020-12-01 21:18:16 +00:00
mode:
type: integer
description: 1 means encrypted using a master key
Updating typos in openapi/swagger documentation as well as various markdown documentation files (#816) Signed-off-by: Dylan Legendre <dylanlegendre09@gmail.com>
2022-05-05 16:26:22 +00:00
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 existing secret will be preserved
add basic S3-Compatible Object Storage support we have now an interface for filesystem backeds, this make easy to add new filesystem backends
2020-01-19 06:41:05 +00:00
S3Config:
type: object
properties:
bucket:
type: string
minLength: 1
region:
type: string
minLength: 1
access_key:
type: string
access_secret:
add a dedicated struct to store encrypted credentials also gcs credentials are now encrypted, both on disk and inside the provider. Data provider is automatically migrated and load data will accept old format too but you should upgrade to the new format to avoid future issues
2020-11-22 20:53:04 +00:00
$ref: '#/components/schemas/Secret'
S3: add support for assume role Fixes #736 Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-02-28 19:19:13 +00:00
role_arn:
type: string
allow placeholders for add/update users and folders remove session token for S3, a temporary token is useless for our usage Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-03-27 14:32:21 +00:00
description: 'Optional IAM Role ARN to assume'
add basic S3-Compatible Object Storage support we have now an interface for filesystem backeds, this make easy to add new filesystem backends
2020-01-19 06:41:05 +00:00
endpoint:
type: string
description: optional endpoint
storage_class:
type: string
S3: add ACL support Fixes #610
2021-11-13 15:05:40 +00:00
acl:
type: string
description: 'The canned ACL to apply to uploaded objects. Leave empty to use the default ACL. For more information and available ACLs, see here: https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl'
s3: add documentation and test cases for upload part size
2020-03-13 16:28:55 +00:00
upload_part_size:
type: integer
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
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.'
s3: add documentation and test cases for upload part size
2020-03-13 16:28:55 +00:00
upload_concurrency:
type: integer
S3: expose more properties, possible backward incompatible change Before these changes we implictly set S3ForcePathStyle if an endpoint was provided. This can cause issues with some S3 compatible object storages and must be explicitly set now. AWS is also deprecating this setting https://aws.amazon.com/it/blogs/aws/amazon-s3-path-deprecation-plan-the-rest-of-the-story/
2021-07-23 14:56:48 +00:00
description: 'the number of parts to upload in parallel. If this value is set to zero, the default value (5) will be used'
S3: add a timeout for single part uploads Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-02-01 11:15:56 +00:00
upload_part_max_time:
type: integer
description: 'the maximum time allowed, in seconds, to upload a single chunk (the chunk size is defined via "upload_part_size"). 0 means no timeout'
S3: expose more properties, possible backward incompatible change Before these changes we implictly set S3ForcePathStyle if an endpoint was provided. This can cause issues with some S3 compatible object storages and must be explicitly set now. AWS is also deprecating this setting https://aws.amazon.com/it/blogs/aws/amazon-s3-path-deprecation-plan-the-rest-of-the-story/
2021-07-23 14:56:48 +00:00
download_part_size:
type: integer
description: 'the buffer size (in MB) to use for multipart downloads. 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. Ignored for partial downloads'
download_concurrency:
type: integer
description: 'the number of parts to download in parallel. If this value is set to zero, the default value (5) will be used. Ignored for partial downloads'
s3: allow to configure the chunk download timeout
2021-07-11 16:39:45 +00:00
download_part_max_time:
type: integer
S3: add a timeout for single part uploads Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-02-01 11:15:56 +00:00
description: 'the maximum time allowed, in seconds, to download a single chunk (the chunk size is defined via "download_part_size"). 0 means no timeout. Ignored for partial downloads.'
S3: expose more properties, possible backward incompatible change Before these changes we implictly set S3ForcePathStyle if an endpoint was provided. This can cause issues with some S3 compatible object storages and must be explicitly set now. AWS is also deprecating this setting https://aws.amazon.com/it/blogs/aws/amazon-s3-path-deprecation-plan-the-rest-of-the-story/
2021-07-23 14:56:48 +00:00
force_path_style:
type: boolean
description: 'Set this to "true" to force the request to use path-style addressing, i.e., "http://s3.amazonaws.com/BUCKET/KEY". By default, the S3 client will use virtual hosted bucket addressing when possible ("http://BUCKET.s3.amazonaws.com/KEY")'
S3: add support for serving virtual folders inside the same bucket each user can be assigned to a virtual folder. This is similar to a chroot directory for local filesystem
2020-01-19 22:23:09 +00:00
key_prefix:
type: string
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
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'
S3: add support for serving virtual folders inside the same bucket each user can be assigned to a virtual folder. This is similar to a chroot directory for local filesystem
2020-01-19 22:23:09 +00:00
example: folder/subfolder/
add basic S3-Compatible Object Storage support we have now an interface for filesystem backeds, this make easy to add new filesystem backends
2020-01-19 06:41:05 +00:00
description: S3 Compatible Object Storage configuration details
add support for serving Google Cloud Storage over SFTP/SCP Each user can be mapped with a Google Cloud Storage bucket or a bucket virtual folder
2020-01-31 18:04:00 +00:00
GCSConfig:
type: object
properties:
bucket:
type: string
minLength: 1
credentials:
add a dedicated struct to store encrypted credentials also gcs credentials are now encrypted, both on disk and inside the provider. Data provider is automatically migrated and load data will accept old format too but you should upgrade to the new format to avoid future issues
2020-11-22 20:53:04 +00:00
$ref: '#/components/schemas/Secret'
gcs: add support for automatic credentials We can now also support implicit credentials using the Application Default Credentials strategy
2020-02-19 08:41:15 +00:00
automatic_credentials:
type: integer
enum:
- 0
- 1
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: |
gcs: add support for automatic credentials We can now also support implicit credentials using the Application Default Credentials strategy
2020-02-19 08:41:15 +00:00
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
add support for serving Google Cloud Storage over SFTP/SCP Each user can be mapped with a Google Cloud Storage bucket or a bucket virtual folder
2020-01-31 18:04:00 +00:00
storage_class:
type: string
GCS: add ACL support
2021-11-15 20:57:41 +00:00
acl:
type: string
description: 'The ACL to apply to uploaded objects. Leave empty to use the default ACL. For more information and available ACLs, refer to the JSON API here: https://cloud.google.com/storage/docs/access-control/lists#predefined-acl'
add support for serving Google Cloud Storage over SFTP/SCP Each user can be mapped with a Google Cloud Storage bucket or a bucket virtual folder
2020-01-31 18:04:00 +00:00
key_prefix:
type: string
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
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'
add support for serving Google Cloud Storage over SFTP/SCP Each user can be mapped with a Google Cloud Storage bucket or a bucket virtual folder
2020-01-31 18:04:00 +00:00
example: folder/subfolder/
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
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'
add Azure Blob support
2020-10-25 07:18:48 +00:00
AzureBlobFsConfig:
type: object
properties:
container:
type: string
account_name:
type: string
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: 'Storage Account Name, leave blank to use SAS URL'
add Azure Blob support
2020-10-25 07:18:48 +00:00
account_key:
add a dedicated struct to store encrypted credentials also gcs credentials are now encrypted, both on disk and inside the provider. Data provider is automatically migrated and load data will accept old format too but you should upgrade to the new format to avoid future issues
2020-11-22 20:53:04 +00:00
$ref: '#/components/schemas/Secret'
add Azure Blob support
2020-10-25 07:18:48 +00:00
sas_url:
azblob: store SAS URL as kms.Secret
2021-06-11 20:27:36 +00:00
$ref: '#/components/schemas/Secret'
add Azure Blob support
2020-10-25 07:18:48 +00:00
endpoint:
type: string
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
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"'
add Azure Blob support
2020-10-25 07:18:48 +00:00
upload_part_size:
type: integer
azure blobs: add support for multipart downloads Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-02-21 18:01:31 +00:00
description: 'the buffer size (in MB) to use for multipart uploads. If this value is set to zero, the default value (5MB) will be used.'
add Azure Blob support
2020-10-25 07:18:48 +00:00
upload_concurrency:
type: integer
azure blobs: add support for multipart downloads Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-02-21 18:01:31 +00:00
description: 'the number of parts to upload in parallel. If this value is set to zero, the default value (5) will be used'
download_part_size:
type: integer
description: 'the buffer size (in MB) to use for multipart downloads. If this value is set to zero, the default value (5MB) will be used.'
download_concurrency:
type: integer
description: 'the number of parts to download in parallel. If this value is set to zero, the default value (5) will be used'
Azure Blob: update SDK and add access tier support
2020-10-30 21:17:17 +00:00
access_tier:
type: string
enum:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
- ''
- Archive
- Hot
- Cool
add Azure Blob support
2020-10-25 07:18:48 +00:00
key_prefix:
type: string
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
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'
add Azure Blob support
2020-10-25 07:18:48 +00:00
example: folder/subfolder/
use_emulator:
type: boolean
description: Azure Blob Storage configuration details
add Data At Rest Encryption support
2020-12-05 12:48:13 +00:00
CryptFsConfig:
type: object
properties:
passphrase:
$ref: '#/components/schemas/Secret'
description: Crypt filesystem configuration details
add sftpfs storage backend Fixes #224
2020-12-12 09:31:09 +00:00
SFTPFsConfig:
type: object
properties:
endpoint:
type: string
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: 'remote SFTP endpoint as host:port'
add sftpfs storage backend Fixes #224
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'
Fixes #855 update OpenAPI definition, add test cases, fix lint Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-05-30 17:01:12 +00:00
key_passphrase:
$ref: '#/components/schemas/Secret'
add sftpfs storage backend Fixes #224
2020-12-12 09:31:09 +00:00
fingerprints:
type: array
items:
type: string
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
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'
add sftpfs storage backend Fixes #224
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.
sftpfs: add an option to disable concurrent reads
2021-03-06 14:41:40 +00:00
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.
sftpfs: add buffering support this way we improve performance over high latency networks
2021-04-03 14:00:55 +00:00
buffer_size:
fix OpenAPI schema
2021-04-03 15:09:08 +00:00
type: integer
allow to disable some hooks on a per-user basis This way you can, for example, mix external and internal users
2021-04-04 20:32:25 +00:00
minimum: 0
maximum: 16
example: 2
sftpfs: add buffering support this way we improve performance over high latency networks
2021-04-03 14:00:55 +00:00
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.
add basic S3-Compatible Object Storage support we have now an interface for filesystem backeds, this make easy to add new filesystem backends
2020-01-19 06:41:05 +00:00
FilesystemConfig:
type: object
properties:
provider:
eventsearcher plugin: add support to search for provider, bucket, endpoint Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-01-03 16:02:52 +00:00
$ref: '#/components/schemas/FsProviders'
add basic S3-Compatible Object Storage support we have now an interface for filesystem backeds, this make easy to add new filesystem backends
2020-01-19 06:41:05 +00:00
s3config:
$ref: '#/components/schemas/S3Config'
add support for serving Google Cloud Storage over SFTP/SCP Each user can be mapped with a Google Cloud Storage bucket or a bucket virtual folder
2020-01-31 18:04:00 +00:00
gcsconfig:
$ref: '#/components/schemas/GCSConfig'
add Azure Blob support
2020-10-25 07:18:48 +00:00
azblobconfig:
$ref: '#/components/schemas/AzureBlobFsConfig'
add Data At Rest Encryption support
2020-12-05 12:48:13 +00:00
cryptconfig:
$ref: '#/components/schemas/CryptFsConfig'
add sftpfs storage backend Fixes #224
2020-12-12 09:31:09 +00:00
sftpconfig:
$ref: '#/components/schemas/SFTPFsConfig'
add basic S3-Compatible Object Storage support we have now an interface for filesystem backeds, this make easy to add new filesystem backends
2020-01-19 06:41:05 +00:00
description: Storage filesystem details
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
BaseVirtualFolder:
add support for virtual folders directories outside the user home directory can be exposed as virtual folders
2020-02-23 10:30:26 +00:00
type: object
properties:
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
id:
type: integer
format: int32
minimum: 1
virtual folders: change dataprovider structure This way we no longer depend on the local file system path and so we can add support for cloud backends in future updates
2021-02-01 18:04:15 +00:00
name:
type: string
description: unique name for this virtual folder
add support for virtual folders directories outside the user home directory can be exposed as virtual folders
2020-02-23 10:30:26 +00:00
mapped_path:
type: string
virtual folders: change dataprovider structure This way we no longer depend on the local file system path and so we can add support for cloud backends in future updates
2021-02-01 18:04:15 +00:00
description: absolute filesystem path to use as virtual folder
data providers: add filesystem to folder ... ... and some descriptive fields. The filesystem support for virtual folders will be implemented in future commits
2021-02-24 18:40:29 +00:00
description:
type: string
description: optional description
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
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
extend virtual folders support to all storage backends Fixes #241
2021-03-21 18:15:47 +00:00
filesystem:
$ref: '#/components/schemas/FilesystemConfig'
add basic REST APIs for data retention Fixes #495
2021-09-25 10:20:31 +00:00
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.'
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
VirtualFolder:
allOf:
- $ref: '#/components/schemas/BaseVirtualFolder'
- type: object
properties:
virtual_path:
type: string
quota_size:
type: integer
format: int64
Updating typos in openapi/swagger documentation as well as various markdown documentation files (#816) Signed-off-by: Dylan Legendre <dylanlegendre09@gmail.com>
2022-05-05 16:26:22 +00:00
description: 'Quota as size in bytes. 0 means 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'
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
quota_files:
type: integer
format: int32
Updating typos in openapi/swagger documentation as well as various markdown documentation files (#816) Signed-off-by: Dylan Legendre <dylanlegendre09@gmail.com>
2022-05-05 16:26:22 +00:00
description: 'Quota as number of files. 0 means 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'
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
required:
- virtual_path
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
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.'
first version
2019-07-20 10:26:52 +00:00
User:
type: object
properties:
id:
type: integer
format: int32
minimum: 1
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 10:36:21 +00:00
status:
type: integer
enum:
- 0
- 1
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: |
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 10:36:21 +00:00
status:
* `0` user is disabled, login is not allowed
* `1` user is enabled
first version
2019-07-20 10:26:52 +00:00
username:
type: string
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
description: username is unique
Added email field for user account
2021-09-25 17:06:13 +00:00
email:
type: string
format: email
data providers: add filesystem to folder ... ... and some descriptive fields. The filesystem support for virtual folders will be implemented in future commits
2021-02-24 18:40:29 +00:00
description:
type: string
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: 'optional description, for example the user full name'
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 10:36:21 +00:00
expiration_date:
type: integer
format: int64
description: expiration date as unix timestamp in milliseconds. An expired account cannot login. 0 means no expiration
first version
2019-07-20 10:26:52 +00:00
password:
type: string
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
format: password
docs: fix a typo
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
rename public_key in public_keys remove compatibility layer to convert public keys newline delimited in json list
2019-08-07 21:41:10 +00:00
public_keys:
convert public key from newline delimited string to a real array Added a compatibility layer that will convert newline delimited keys to array when the user is fetched from the database. This code will be removed in future versions please update your public keys, you only need to resave the users using the REST API.
2019-08-01 20:42:46 +00:00
type: array
items:
type: string
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
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.
first version
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
add support for virtual folders directories outside the user home directory can be exposed as virtual folders
2020-02-23 10:30:26 +00:00
virtual_folders:
type: array
items:
$ref: '#/components/schemas/VirtualFolder'
add groups support Using groups simplifies the administration of multiple accounts by letting you assign settings once to a group, instead of multiple times to each individual user. Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-04-25 13:49:11 +00:00
description: mapping between virtual SFTPGo paths and virtual folders. 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
first version
2019-07-20 10:26:52 +00:00
uid:
type: integer
format: int32
minimum: 0
Increase uid:gid limits (#362) Fixes #361
2021-03-25 16:11:42 +00:00
maximum: 2147483647
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
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'
first version
2019-07-20 10:26:52 +00:00
gid:
type: integer
format: int32
minimum: 0
Increase uid:gid limits (#362) Fixes #361
2021-03-25 16:11:42 +00:00
maximum: 2147483647
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
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'
first version
2019-07-20 10:26:52 +00:00
max_sessions:
type: integer
format: int32
pre-login program: allow to create a new user too clarify the difference between dynamic user creation/update and external authentication
2020-03-27 22:26:22 +00:00
description: Limit the sessions that a user can open. 0 means unlimited
first version
2019-07-20 10:26:52 +00:00
quota_size:
type: integer
format: int64
Updating typos in openapi/swagger documentation as well as various markdown documentation files (#816) Signed-off-by: Dylan Legendre <dylanlegendre09@gmail.com>
2022-05-05 16:26:22 +00:00
description: Quota as size in bytes. 0 means 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
first version
2019-07-20 10:26:52 +00:00
quota_files:
type: integer
format: int32
Updating typos in openapi/swagger documentation as well as various markdown documentation files (#816) Signed-off-by: Dylan Legendre <dylanlegendre09@gmail.com>
2022-05-05 16:26:22 +00:00
description: Quota as number of files. 0 means 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
first version
2019-07-20 10:26:52 +00:00
permissions:
add per directory permissions we can now have permissions such as these ones {"/":["*"],"/somedir":["list","download"]} The old permissions are automatically converted to the new structure, no database migration is needed
2019-12-25 17:20:19 +00:00
type: object
first version
2019-07-20 10:26:52 +00:00
items:
add per directory permissions we can now have permissions such as these ones {"/":["*"],"/somedir":["list","download"]} The old permissions are automatically converted to the new structure, no database migration is needed
2019-12-25 17:20:19 +00:00
$ref: '#/components/schemas/DirPermissions'
first version
2019-07-20 10:26:52 +00:00
minItems: 1
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
example:
/:
- '*'
/somedir:
- list
- download
first version
2019-07-20 10:26:52 +00:00
used_quota_size:
type: integer
format: int64
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
used_quota_files:
first version
2019-07-20 10:26:52 +00:00
type: integer
format: int32
rename last_quota_scan to last_quota_update Existing databases must be updated using the script 20190728.sql
2019-07-28 17:29:32 +00:00
last_quota_update:
first version
2019-07-20 10:26:52 +00:00
type: integer
format: int64
Add support for allowed/denied IP/Mask Login can be restricted to specific ranges of IP address or to a specific IP address. Please apply the appropriate SQL upgrade script to add the filter field to your database. The filter database field will allow to add other filters without requiring a new database migration
2019-12-30 17:37:50 +00:00
description: Last quota update as unix timestamp in milliseconds
first version
2019-07-20 10:26:52 +00:00
upload_bandwidth:
type: integer
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: 'Maximum upload bandwidth as KB/s, 0 means unlimited'
first version
2019-07-20 10:26:52 +00:00
download_bandwidth:
type: integer
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: 'Maximum download bandwidth as KB/s, 0 means unlimited'
add support for data transfer bandwidth limits with total limit or separate settings for uploads and downloads and overrides based on the client's IP address. Limits can be reset using the REST API Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-01-30 10:42:36 +00:00
upload_data_transfer:
type: integer
description: 'Maximum data transfer allowed for uploads as MB. 0 means no limit'
download_data_transfer:
type: integer
description: 'Maximum data transfer allowed for downloads as MB. 0 means no limit'
total_data_transfer:
type: integer
description: 'Maximum total data transfer as MB. 0 means unlimited. You can set a total data transfer instead of the individual values for uploads and downloads'
used_upload_data_transfer:
type: integer
description: 'Uploaded size, as bytes, since the last reset'
used_download_data_transfer:
type: integer
description: 'Downloaded size, as bytes, since the last reset'
dataprovider: add timestamp fields for users and admins
2021-08-19 13:51:43 +00:00
created_at:
type: integer
format: int64
description: 'creation time as unix timestamp in milliseconds. It will be 0 for users created before v2.2.0'
updated_at:
type: integer
format: int64
description: last update time as unix timestamp in milliseconds
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 10:36:21 +00:00
last_login:
type: integer
format: int64
add KMS support Fixes #226
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
Add support for allowed/denied IP/Mask Login can be restricted to specific ranges of IP address or to a specific IP address. Please apply the appropriate SQL upgrade script to add the filter field to your database. The filter database field will allow to add other filters without requiring a new database migration
2019-12-30 17:37:50 +00:00
filters:
$ref: '#/components/schemas/UserFilters'
add basic S3-Compatible Object Storage support we have now an interface for filesystem backeds, this make easy to add new filesystem backends
2020-01-19 06:41:05 +00:00
filesystem:
$ref: '#/components/schemas/FilesystemConfig'
user: add a free text field Fixes #230
2020-11-25 21:26:34 +00:00
additional_info:
type: string
description: Free form text field for external systems
add groups support Using groups simplifies the administration of multiple accounts by letting you assign settings once to a group, instead of multiple times to each individual user. Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-04-25 13:49:11 +00:00
groups:
type: array
items:
$ref: '#/components/schemas/GroupMapping'
OIDC: add support for custom fields These fields can be used in the pre-login hook to implement custom logics Fixes #787 Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-04-12 17:31:25 +00:00
oidc_custom_fields:
type: object
additionalProperties: true
description: 'This field is passed to the pre-login hook if custom OIDC token fields have been configured. Field values can be of any type (this is a free form object) and depend on the type of the configured OIDC token fields'
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
AdminFilters:
type: object
properties:
allow_list:
type: array
items:
type: string
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
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'
REST API: add support for API key authentication
2021-08-17 16:08:32 +00:00
allow_api_key_auth:
type: boolean
description: 'API key auth allows to impersonate this administrator with an API key'
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
totp_config:
$ref: '#/components/schemas/AdminTOTPConfig'
recovery_codes:
type: array
items:
$ref: '#/components/schemas/RecoveryCode'
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
Admin:
type: object
properties:
id:
type: integer
format: int32
minimum: 1
status:
type: integer
enum:
- 0
- 1
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: |
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
status:
* `0` user is disabled, login is not allowed
* `1` user is enabled
username:
type: string
description: username is unique
data providers: add filesystem to folder ... ... and some descriptive fields. The filesystem support for virtual folders will be implemented in future commits
2021-02-24 18:40:29 +00:00
description:
type: string
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: 'optional description, for example the admin full name'
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
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
dataprovider: add timestamp fields for users and admins
2021-08-19 13:51:43 +00:00
created_at:
type: integer
format: int64
description: 'creation time as unix timestamp in milliseconds. It will be 0 for admins created before v2.2.0'
updated_at:
type: integer
format: int64
description: last update time as unix timestamp in milliseconds
last_login:
type: integer
format: int64
description: Last user login as unix timestamp in milliseconds. It is saved at most once every 10 minutes
rework user and admin profiles users and admins can now also update their email and description
2021-09-29 16:46:15 +00:00
AdminProfile:
type: object
properties:
email:
type: string
format: email
description:
type: string
allow_api_key_auth:
type: boolean
description: 'If enabled, you can impersonate this admin, in REST API, using an API key. If disabled admin credentials are required for impersonation'
UserProfile:
type: object
properties:
email:
type: string
format: email
description:
type: string
allow_api_key_auth:
type: boolean
description: 'If enabled, you can impersonate this user, in REST API, using an API key. If disabled user credentials are required for impersonation'
public_keys:
type: array
items:
type: string
example: ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEUWwDwEWhTbF0MqAsp/oXK1HR2cElhM8oo1uVmL3ZeDKDiTm4ljMr92wfTgIGDqIoxmVqgYIkAOAhuykAVWBzc= user@host
description: Public keys in OpenSSH format
REST API: add support for API key authentication
2021-08-17 16:08:32 +00:00
APIKey:
type: object
properties:
id:
type: string
description: unique key identifier
name:
type: string
description: User friendly key name
key:
type: string
format: password
description: We store the hash of the key. This is just like a password. For security reasons this field is omitted when you search/get API keys
scope:
$ref: '#/components/schemas/APIKeyScope'
created_at:
type: integer
format: int64
description: creation time as unix timestamp in milliseconds
updated_at:
type: integer
format: int64
description: last update time as unix timestamp in milliseconds
last_use_at:
type: integer
format: int64
description: last use time as unix timestamp in milliseconds. It is saved at most once every 10 minutes
expires_at:
type: integer
format: int64
description: expiration time as unix timestamp in milliseconds
description:
type: string
description: optional description
user:
type: string
description: username associated with this API key. If empty and the scope is "user scope" the key can impersonate any user
admin:
type: string
description: admin associated with this API key. If empty and the scope is "admin scope" the key can impersonate any admin
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
QuotaUsage:
type: object
properties:
used_quota_size:
type: integer
format: int64
used_quota_files:
type: integer
format: int32
add support for data transfer bandwidth limits with total limit or separate settings for uploads and downloads and overrides based on the client's IP address. Limits can be reset using the REST API Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-01-30 10:42:36 +00:00
TransferQuotaUsage:
type: object
properties:
used_upload_data_transfer:
type: integer
format: int64
description: 'The value must be specified as bytes'
used_download_data_transfer:
type: integer
format: int64
description: 'The value must be specified as bytes'
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 12:41:15 +00:00
Transfer:
first version
2019-07-20 10:26:52 +00:00
type: object
properties:
operation_type:
type: string
dataprovider: add support for user status and expiration an user can now be disabled or expired. If you are using an SQL database as dataprovider please remember to execute the sql update script inside "sql" folder. Fixes #57
2019-11-13 10:36:21 +00:00
enum:
first version
2019-07-20 10:26:52 +00:00
- upload
- download
extend virtual folders support to all storage backends Fixes #241
2021-03-21 18:15:47 +00:00
description: |
Operations:
* `upload`
* `download`
sftpd stats: add file path for active upload/download
2019-08-08 17:33:16 +00:00
path:
type: string
sftpd: add support for some SSH commands md5sum, sha1sum are used by rclone. cd, pwd improve the support for RemoteFiles mobile app. These commands are all implemented inside SFTPGo so they work even if the matching system commands are not available, for example on Windows
2019-11-18 22:30:37 +00:00
description: file path for the upload/download
first version
2019-07-20 10:26:52 +00:00
start_time:
type: integer
format: int64
rename last_quota_scan to last_quota_update Existing databases must be updated using the script 20190728.sql
2019-07-28 17:29:32 +00:00
description: start time as unix timestamp in milliseconds
first version
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
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 12:41:15 +00:00
description: unique connection identifier
first version
2019-07-20 10:26:52 +00:00
client_version:
type: string
sftpd: add support for some SSH commands md5sum, sha1sum are used by rclone. cd, pwd improve the support for RemoteFiles mobile app. These commands are all implemented inside SFTPGo so they work even if the matching system commands are not available, for example on Windows
2019-11-18 22:30:37 +00:00
description: client version
first version
2019-07-20 10:26:52 +00:00
remote_address:
type: string
sftpd: add support for some SSH commands md5sum, sha1sum are used by rclone. cd, pwd improve the support for RemoteFiles mobile app. These commands are all implemented inside SFTPGo so they work even if the matching system commands are not available, for example on Windows
2019-11-18 22:30:37 +00:00
description: Remote address for the connected client
first version
2019-07-20 10:26:52 +00:00
connection_time:
type: integer
format: int64
rename last_quota_scan to last_quota_update Existing databases must be updated using the script 20190728.sql
2019-07-28 17:29:32 +00:00
description: connection time as unix timestamp in milliseconds
add WebDAV support Fixes #147
2020-08-11 21:56:10 +00:00
command:
sftpd: add support for some SSH commands md5sum, sha1sum are used by rclone. cd, pwd improve the support for RemoteFiles mobile app. These commands are all implemented inside SFTPGo so they work even if the matching system commands are not available, for example on Windows
2019-11-18 22:30:37 +00:00
type: string
OpenAPI: minor changes
2021-01-18 12:24:38 +00:00
description: Last SSH/FTP command or WebDAV method
first version
2019-07-20 10:26:52 +00:00
last_activity:
type: integer
format: int64
rename last_quota_scan to last_quota_update Existing databases must be updated using the script 20190728.sql
2019-07-28 17:29:32 +00:00
description: last client activity as unix timestamp in milliseconds
add SCP support SCP is an experimental feature, we have our own SCP implementation since we can't rely on scp system command to proper handle permissions, quota and user's home dir restrictions. The SCP protocol is quite simple but there is no official docs about it, so we need more testing and feedbacks before enabling it by default. We may not handle some borderline cases or have sneaky bugs. This commit contains some breaking changes to the REST API. SFTPGo API should be stable now and I hope no more breaking changes before the first stable release.
2019-08-24 12:41:15 +00:00
protocol:
type: string
enum:
- SFTP
- SCP
sftpd: add support for some SSH commands md5sum, sha1sum are used by rclone. cd, pwd improve the support for RemoteFiles mobile app. These commands are all implemented inside SFTPGo so they work even if the matching system commands are not available, for example on Windows
2019-11-18 22:30:37 +00:00
- SSH
add WebDAV support Fixes #147
2020-08-11 21:56:10 +00:00
- FTP
- DAV
first version
2019-07-20 10:26:52 +00:00
active_transfers:
type: array
items:
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
$ref: '#/components/schemas/Transfer'
add basic REST APIs for data retention Fixes #495
2021-09-25 10:20:31 +00:00
FolderRetention:
type: object
properties:
path:
type: string
description: 'exposed virtual directory path, if no other specific retention is defined, the retention applies for sub directories too. For example if retention is defined for the paths "/" and "/sub" then the retention for "/" is applied for any file outside the "/sub" directory'
example: '/'
retention:
type: integer
description: retention time in hours. All the files with a modification time older than the defined value will be deleted. 0 means exclude this path
example: 24
delete_empty_dirs:
type: boolean
description: if enabled, empty directories will be deleted
ignore_user_permissions:
type: boolean
description: 'if enabled, files will be deleted even if the user does not have the delete permission. The default is "false" which means that files will be skipped if the user does not have permission to delete them. File patterns filters will always be silently ignored'
RetentionCheck:
type: object
properties:
username:
type: string
description: username to which the retention check refers
folders:
type: array
items:
$ref: '#/components/schemas/FolderRetention'
start_time:
type: integer
format: int64
description: check start time as unix timestamp in milliseconds
add data retention check hook
2021-10-03 13:17:49 +00:00
notifications:
type: array
items:
$ref: '#/components/schemas/RetentionCheckNotification'
data retention: allow to notify results via e-mail
2021-10-02 20:25:41 +00:00
email:
type: string
format: email
description: 'if the notification method is set to "Email", this is the e-mail address that receives the retention check report. This field is automatically set to the email address associated with the administrator starting the check'
add support for metadata plugins
2021-12-16 17:18:36 +00:00
MetadataCheck:
type: object
properties:
username:
type: string
description: username to which the check refers
start_time:
type: integer
format: int64
description: check start time as unix timestamp in milliseconds
first version
2019-07-20 10:26:52 +00:00
QuotaScan:
type: object
properties:
username:
type: string
add basic REST APIs for data retention Fixes #495
2021-09-25 10:20:31 +00:00
description: username to which the quota scan refers
first version
2019-07-20 10:26:52 +00:00
start_time:
type: integer
format: int64
rename last_quota_scan to last_quota_update Existing databases must be updated using the script 20190728.sql
2019-07-28 17:29:32 +00:00
description: scan start time as unix timestamp in milliseconds
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
FolderQuotaScan:
type: object
properties:
extend virtual folders support to all storage backends Fixes #241
2021-03-21 18:15:47 +00:00
name:
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
type: string
add basic REST APIs for data retention Fixes #495
2021-09-25 10:20:31 +00:00
description: folder name to which the quota scan refers
refactor virtual folders The same virtual folder can now be shared among users and different folder quota limits for each user are supported. Fixes #120
2020-06-07 21:30:18 +00:00
start_time:
type: integer
format: int64
description: scan start time as unix timestamp in milliseconds
improve defender and quotas REST API
2021-06-07 19:52:43 +00:00
DefenderEntry:
type: object
properties:
id:
type: string
ip:
type: string
score:
type: integer
description: the score increases whenever a violation is detected, such as an attempt to log in using an incorrect password or invalid username. If the score exceeds the configured threshold, the IP is banned. Omitted for banned IPs
ban_time:
type: string
format: date-time
description: date time until the IP is banned. For already banned hosts, the ban time is increased each time a new violation is detected. Omitted if the IP is not banned
REST API: add a method to get the status of the services added a status page to the built-in web admin
2020-12-08 10:18:34 +00:00
SSHHostKey:
type: object
properties:
path:
type: string
fingerprint:
type: string
add support for multiple bindings Fixes #253
2020-12-23 15:12:30 +00:00
SSHBinding:
REST API: add a method to get the status of the services added a status page to the built-in web admin
2020-12-08 10:18:34 +00:00
type: object
properties:
add support for multiple bindings Fixes #253
2020-12-23 15:12:30 +00:00
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
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: 'apply the proxy configuration, if any'
add support for multiple bindings Fixes #253
2020-12-23 15:12:30 +00:00
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:
REST API: add a method to get the status of the services added a status page to the built-in web admin
2020-12-08 10:18:34 +00:00
type: boolean
add more details to the server status page add all supported fields to the OpenAPI docs Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-02-26 15:43:29 +00:00
min_tls_version:
$ref: '#/components/schemas/TLSVersions'
update OpenAPI schema
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
add more details to the server status page add all supported fields to the OpenAPI docs Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-02-26 15:43:29 +00:00
tls_cipher_suites:
type: array
items:
type: string
description: 'List of supported cipher suites for TLS version 1.2. If empty a default list of secure cipher suites is used, with a preference order based on hardware performance'
prefix:
type: string
description: 'Prefix for WebDAV resources, if empty WebDAV resources will be available at the `/` URI'
proxy_allowed:
type: array
items:
type: string
description: 'List of IP addresses and IP ranges allowed to set proxy headers'
PassiveIPOverride:
type: object
properties:
networks:
type: array
items:
type: string
ip:
type: string
add support for multiple bindings Fixes #253
2020-12-23 15:12:30 +00:00
FTPDBinding:
type: object
properties:
REST API: add a method to get the status of the services added a status page to the built-in web admin
2020-12-08 10:18:34 +00:00
address:
type: string
add support for multiple bindings Fixes #253
2020-12-23 15:12:30 +00:00
description: TCP address the server listen on
port:
type: integer
description: the port used for serving requests
apply_proxy_config:
type: boolean
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: 'apply the proxy configuration, if any'
add support for multiple bindings Fixes #253
2020-12-23 15:12:30 +00:00
tls_mode:
type: integer
enum:
- 0
- 1
- 2
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: |
keyboard interactive hooks: allow to validate passcode
2021-12-04 14:14:44 +00:00
TLS mode:
* `0` - clear or explicit TLS
* `1` - explicit TLS required
* `2` - implicit TLS
add more details to the server status page add all supported fields to the OpenAPI docs Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-02-26 15:43:29 +00:00
min_tls_version:
$ref: '#/components/schemas/TLSVersions'
add support for multiple bindings Fixes #253
2020-12-23 15:12:30 +00:00
force_passive_ip:
type: string
description: External IP address to expose for passive connections
add more details to the server status page add all supported fields to the OpenAPI docs Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-02-26 15:43:29 +00:00
passive_ip_overrides:
type: array
items:
$ref: '#/components/schemas/PassiveIPOverride'
update OpenAPI schema
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
add more details to the server status page add all supported fields to the OpenAPI docs Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-02-26 15:43:29 +00:00
tls_cipher_suites:
type: array
items:
type: string
description: 'List of supported cipher suites for TLS version 1.2. If empty a default list of secure cipher suites is used, with a preference order based on hardware performance'
passive_connections_security:
type: integer
enum:
- 0
- 1
description: |
Active connections security:
* `0` - require matching peer IP addresses of control and data connection
* `1` - disable any checks
active_connections_security:
type: integer
enum:
- 0
- 1
description: |
Active connections security:
* `0` - require matching peer IP addresses of control and data connection
* `1` - disable any checks
debug:
type: boolean
description: 'If enabled any FTP command will be logged'
REST API: add a method to get the status of the services added a status page to the built-in web admin
2020-12-08 10:18:34 +00:00
SSHServiceStatus:
add support for multiple bindings Fixes #253
2020-12-23 15:12:30 +00:00
type: object
properties:
is_active:
type: boolean
bindings:
type: array
items:
$ref: '#/components/schemas/SSHBinding'
OpenAPI: minor changes
2021-01-18 12:24:38 +00:00
nullable: true
add support for multiple bindings Fixes #253
2020-12-23 15:12:30 +00:00
host_keys:
type: array
items:
$ref: '#/components/schemas/SSHHostKey'
OpenAPI: minor changes
2021-01-18 12:24:38 +00:00
nullable: true
add support for multiple bindings Fixes #253
2020-12-23 15:12:30 +00:00
ssh_commands:
OpenAPI: minor changes
2021-01-18 12:24:38 +00:00
type: array
items:
type: string
add more details to the server status page add all supported fields to the OpenAPI docs Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-02-26 15:43:29 +00:00
authentications:
type: array
items:
$ref: '#/components/schemas/SSHAuthentications'
REST API: add a method to get the status of the services added a status page to the built-in web admin
2020-12-08 10:18:34 +00:00
FTPPassivePortRange:
type: object
properties:
start:
type: integer
end:
type: integer
FTPServiceStatus:
add support for multiple bindings Fixes #253
2020-12-23 15:12:30 +00:00
type: object
properties:
is_active:
type: boolean
bindings:
type: array
items:
$ref: '#/components/schemas/FTPDBinding'
OpenAPI: minor changes
2021-01-18 12:24:38 +00:00
nullable: true
add support for multiple bindings Fixes #253
2020-12-23 15:12:30 +00:00
passive_port_range:
$ref: '#/components/schemas/FTPPassivePortRange'
REST API: add a method to get the status of the services added a status page to the built-in web admin
2020-12-08 10:18:34 +00:00
WebDAVServiceStatus:
add support for multiple bindings Fixes #253
2020-12-23 15:12:30 +00:00
type: object
properties:
is_active:
type: boolean
bindings:
type: array
items:
$ref: '#/components/schemas/WebDAVBinding'
OpenAPI: minor changes
2021-01-18 12:24:38 +00:00
nullable: true
REST API: add a method to get the status of the services added a status page to the built-in web admin
2020-12-08 10:18:34 +00:00
DataProviderStatus:
type: object
properties:
is_active:
type: boolean
driver:
type: string
error:
type: string
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
MFAStatus:
type: object
properties:
is_active:
type: boolean
totp_configs:
type: array
items:
$ref: '#/components/schemas/TOTPConfig'
REST API: add a method to get the status of the services added a status page to the built-in web admin
2020-12-08 10:18:34 +00:00
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'
add REST API for the defender
2021-01-02 18:33:24 +00:00
defender:
type: object
properties:
is_active:
type: boolean
add builtin two-factor auth support The builtin two-factor authentication is based on time-based one time passwords (RFC 6238) which works with Authy, Google Authenticator and other compatible apps.
2021-09-04 10:11:04 +00:00
mfa:
$ref: '#/components/schemas/MFAStatus'
add REST API for the defender
2021-01-02 18:33:24 +00:00
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
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
Share:
type: object
properties:
id:
type: string
description: auto-generated unique share identifier
name:
type: string
description:
type: string
description: optional description
scope:
$ref: '#/components/schemas/ShareScope'
paths:
type: array
items:
type: string
description: 'paths to files or directories, for share scope write this array must contain exactly one directory. Paths will not be validated on save so you can also create them after creating the share'
example:
- '/dir1'
- '/dir2/file.txt'
- '/dir3/subdir'
username:
type: string
created_at:
type: integer
format: int64
description: 'creation time as unix timestamp in milliseconds'
updated_at:
type: integer
format: int64
description: 'last update time as unix timestamp in milliseconds'
last_use_at:
type: integer
format: int64
description: last use time as unix timestamp in milliseconds
expires_at:
type: integer
format: int64
description: 'optional share expiration, as unix timestamp in milliseconds. 0 means no expiration'
password:
type: string
description: 'optional password to protect the share. The special value "[**redacted**]" means that a password has been set, you can use this value if you want to preserve the current password when you update a share'
max_tokens:
type: integer
description: 'maximum allowed access tokens. 0 means no limit'
used_tokens:
type: integer
allow_from:
type: array
items:
type: string
description: 'Limit the share availability to these IP/Mask. 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". An empty list means no restrictions'
example:
- 192.0.2.0/24
- '2001:db8::/32'
add groups support Using groups simplifies the administration of multiple accounts by letting you assign settings once to a group, instead of multiple times to each individual user. Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-04-25 13:49:11 +00:00
GroupUserSettings:
type: object
properties:
home_dir:
type: string
max_sessions:
type: integer
format: int32
quota_size:
type: integer
format: int64
quota_files:
type: integer
format: int32
permissions:
type: object
items:
$ref: '#/components/schemas/DirPermissions'
minItems: 1
example:
/:
- '*'
/somedir:
- list
- download
upload_bandwidth:
type: integer
description: 'Maximum upload bandwidth as KB/s'
download_bandwidth:
type: integer
description: 'Maximum download bandwidth as KB/s'
upload_data_transfer:
type: integer
description: 'Maximum data transfer allowed for uploads as MB'
download_data_transfer:
type: integer
description: 'Maximum data transfer allowed for downloads as MB'
total_data_transfer:
type: integer
description: 'Maximum total data transfer as MB'
filters:
$ref: '#/components/schemas/BaseUserFilters'
Group:
type: object
properties:
id:
type: integer
format: int32
minimum: 1
name:
type: string
description: name is unique
description:
type: string
description: 'optional description'
created_at:
type: integer
format: int64
description: creation time as unix timestamp in milliseconds
updated_at:
type: integer
format: int64
description: last update time as unix timestamp in milliseconds
user_settings:
$ref: '#/components/schemas/GroupUserSettings'
virtual_folders:
type: array
items:
$ref: '#/components/schemas/VirtualFolder'
description: mapping between virtual SFTPGo paths and folders
users:
type: array
items:
type: string
description: list of usernames associated with this group
GroupMapping:
type: object
properties:
name:
type: string
description: group name
type:
enum:
- 1
- 2
description: |
Group type:
* `1` - Primary group
* `2` - Secondaru group
web admin: add backup/restore
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'
add groups support Using groups simplifies the administration of multiple accounts by letting you assign settings once to a group, instead of multiple times to each individual user. Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-04-25 13:49:11 +00:00
groups:
type: array
items:
$ref: '#/components/schemas/Group'
web admin: add backup/restore
2021-01-22 18:42:18 +00:00
admins:
type: array
items:
$ref: '#/components/schemas/Admin'
REST API: add support for API key authentication
2021-08-17 16:08:32 +00:00
api_keys:
WebClient/REST API: add sharing support
2021-11-06 13:13:20 +00:00
type: array
items:
$ref: '#/components/schemas/APIKey'
shares:
type: array
items:
$ref: '#/components/schemas/Share'
web admin: add backup/restore
2021-01-22 18:42:18 +00:00
version:
type: integer
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
PwdChange:
type: object
properties:
current_password:
type: string
new_password:
type: string
OpenAPI: add users API These new APIs match the web client features. I'm aware that some API do not follow REST best practises. I want to avoid things likes "/user/folders/<path>" where "path" must be encoded and making it optional create issues, so I defined resources as query parameters instead of path parameters
2021-06-05 14:07:09 +00:00
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
plugins: improve notifier and searcher
2021-10-20 17:39:49 +00:00
FsEvent:
type: object
properties:
id:
type: string
timestamp:
type: integer
format: int64
description: 'unix timestamp in nanoseconds'
action:
$ref: '#/components/schemas/FsEventAction'
username:
type: string
fs_path:
type: string
fs_target_path:
type: string
virtual_path:
type: string
virtual_target_path:
type: string
ssh_cmd:
type: string
file_size:
type: integer
format: int64
status:
$ref: '#/components/schemas/FsEventStatus'
protocol:
$ref: '#/components/schemas/EventProtocols'
ip:
type: string
update OpenAPI schema
2021-12-04 16:57:48 +00:00
session_id:
type: string
eventsearcher plugin: add support to search for provider, bucket, endpoint Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-01-03 16:02:52 +00:00
fs_provider:
$ref: '#/components/schemas/FsProviders'
bucket:
type: string
endpoint:
type: string
open_flags:
type: string
plugins: improve notifier and searcher
2021-10-20 17:39:49 +00:00
instance_id:
type: string
ProviderEvent:
type: object
properties:
id:
type: string
timestamp:
type: integer
format: int64
description: 'unix timestamp in nanoseconds'
action:
$ref: '#/components/schemas/ProviderEventAction'
username:
type: string
ip:
type: string
object_type:
$ref: '#/components/schemas/ProviderEventObjectType'
object_name:
type: string
instance_id:
type: string
first version
2019-07-20 10:26:52 +00:00
ApiResponse:
type: object
properties:
message:
type: string
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: 'message, can be empty'
first version
2019-07-20 10:26:52 +00:00
error:
type: string
description: error description if any
add version info
2019-08-08 08:01:33 +00:00
VersionInfo:
type: object
properties:
version:
type: string
build_date:
type: string
commit_hash:
type: string
add support for build tag to allow to disable some features The following build tags are available: - "nogcs", disable Google Cloud Storage backend - "nos3", disable S3 Compabible Object Storage backends - "nobolt", disable Bolt data provider - "nomysql", disable MySQL data provider - "nopgsql", disable PostgreSQL data provider - "nosqlite", disable SQLite data provider - "noportable", disable portable mode
2020-05-23 09:58:05 +00:00
features:
type: array
items:
type: string
azure blobs: add support for multipart downloads Signed-off-by: Nicola Murino <nicola.murino@gmail.com>
2022-02-21 18:01:31 +00:00
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'
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
Token:
type: object
properties:
access_token:
type: string
expires_at:
type: string
format: date-time
httpd: add support for basic auth and HTTPS
2020-02-03 23:08:00 +00:00
securitySchemes:
BasicAuth:
type: http
scheme: basic
REST API v2 - add JWT authentication - admins are now stored inside the data provider - admin access can be restricted based on the source IP: both proxy header and connection IP are checked - deprecate REST API CLI: it is not relevant anymore Some other changes to the REST API can still happen before releasing SFTPGo 2.0.0 Fixes #197
2021-01-17 21:29:08 +00:00
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
REST API: add support for API key authentication
2021-08-17 16:08:32 +00:00
APIKeyAuth:
type: apiKey
in: header
name: X-SFTPGO-API-KEY
description: 'API key to use for authentication. API key authentication is intrinsically less secure than using a short lived JWT token. You should prefer API key authentication only for machine-to-machine communications in trusted environments. If no admin/user is associated to the provided key you need to add ".username" at the end of the key. For example if your API key is "6ajKLwswLccVBGpZGv596G.ySAXc8vtp9hMiwAuaLtzof" and you want to impersonate the admin with username "myadmin" you have to use "6ajKLwswLccVBGpZGv596G.ySAXc8vtp9hMiwAuaLtzof.myadmin" as API key. When using API key authentication you cannot manage API keys, update the impersonated admin, change password or public keys for the impersonated user.'
Reference in a new issue Copy permalink