beenull/sftpgo
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
sftpgo/httpd/schema/openapi.yaml

4655 lines
156 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
- 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
- name: users API
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: |
plugins: improve notifier and searcher
2021-10-20 17:39:49 +00:00
SFTPGo allows to securely share your files over SFTP and optionally FTP/S and WebDAV as well.
Add a Getting Started Guide
2021-05-20 16:16:27 +00:00
Several storage backends are supported and they are configurable per user, so you can serve a local directory for a user and an S3 bucket (or part of it) for another one.
SFTPGo also supports virtual folders, a virtual folder can use any of the supported storage backends. So you can have, for example, an S3 user that exposes a GCS bucket (or part of it) on a specified path and an encrypted local filesystem on another one.
Virtual folders can be private or shared among multiple users, for shared virtual folders you can define different quota limits for each user.
fix a possible nil pointer dereference it can happen by upgrading from very old versions
2021-09-11 12:19:17 +00:00
version: 2.1.2-dev
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
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 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
summary: Update quota usage limits
description: Sets the current used quota limits for the given user
operationId: user_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'
/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
description: Ordering folders by path. Default ASC
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'
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
- 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'
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'
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:
REST API: add support for API key authentication
2021-08-17 16:08:32 +00:00
* `0` New users/admins/API keys are added, existing ones are updated. This is the default
* `1` New users/admins/API keys are added, existing ones are not modified
* `2` New users/admins/API keys 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
description: 'Restores SFTPGo data from a JSON backup file on the server. Users, folders and admins will be restored one by one and the restore is stopped if a user/folder/admin cannot be added or updated, so it could happen a partial restore'
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
description: 'Restores SFTPGo data from a JSON backup. Users, folders and admins will be restored one by one and the restore is stopped if a user/folder/admin cannot be added or updated, so it could happen a partial restore'
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:
- users API
summary: Change user password
description: Changes the password for the logged in user
operationId: change_user_password
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PwdChange'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/user/publickeys:
get:
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:
- users API
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:
- users API
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:
- users API
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:
- users API
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:
- users API
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:
- users API
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:
- users API
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:
- users API
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:
- users API
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:
- users API
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'
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:
- users API
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
description: Path to the folder to read. It must be URL encoded, for example the path "my dir/àdir" must be sent as "my%20dir%2F%C3%A0dir". If empty or missing the root folder is assumed
schema:
type: string
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DirEntry'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
/user/dirs:
get:
tags:
- users API
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
description: Path to the folder to read. It must be URL encoded, for example the path "my dir/àdir" must be sent as "my%20dir%2F%C3%A0dir". If empty or missing the root folder is assumed
schema:
type: string
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DirEntry'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
users API: add API to create, delete, rename files and directories
2021-07-23 08:19:27 +00:00
post:
tags:
- users API
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
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:
- users API
summary: Rename a directory
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:
- users API
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:
- users API
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:
- users API
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
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:
- users API
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
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
filename:
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'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
patch:
tags:
- users API
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:
- users API
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'
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:
- users API
summary: Download multiple files and folders as a single zip file
description: A zip file, containing the specified files and folders, will be generated on the fly and returned as response body. Only folders and regular files will be included in the zip
operationId: streamzip
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
type: string
description: Absolute file or folder path
responses:
'200':
description: successful operation
content:
'application/zip':
schema:
type: string
format: binary
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/DefaultResponse'
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:
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
- rename
- 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
* `rename` - rename files or directories is allowed
* `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
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
REST API: add events search
2021-10-23 13:47:21 +00:00
* `view_events` - view and search filesystem and provider events is allowed
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
- 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`
* `password`
* `keyboard-interactive`
* `publickey+password` - multi-step auth: public key and password
* `publickey+keyboard-interactive` - multi-step auth: public key and keyboard interactive
* `TLSCertificate`
* `TLSCertificate+password` - multi-step auth: TLS client certificate and password
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
- DataRetention
description: |
Protocols:
* `SSH` - SSH commands
* `SFTP` - SFTP protocol
* `FTP` - plain FTP and FTPES/FTPS
* `DAV` - WebDAV
* `HTTP` - WebClient/REST API
* `DataRetention` - the event is generated by a data retention check
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
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
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
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
- upload
- delete
- rename
- mkdir
- rmdir
- ssh_cmd
ProviderEventAction:
type: string
enum:
- add
- update
- delete
ProviderEventObjectType:
type: string
enum:
- user
- admin
- 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
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
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: 'list of, case insensitive, allowed shell like file patterns.'
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
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: 'list of, case insensitive, denied shell like file patterns. Denied patterns are evaluated before the allowed ones'
example:
- '*.zip'
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 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
UserFilters:
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'
totp_config:
$ref: '#/components/schemas/UserTOTPConfig'
recovery_codes:
type: array
items:
$ref: '#/components/schemas/RecoveryCode'
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 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
OpenAPI: document that secrets are automatically encrypted before saving
2021-03-28 09:23:06 +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 existig 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'
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 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'
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: 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 maximum time allowed, in seconds, to download a single chunk (the chunk is defined via "download_part_size"). 0 means no timeout. Ignored for partial downloads.'
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
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
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. If this value is set to zero, the default value (4MB) will be used.'
add Azure Blob support
2020-10-25 07:18:48 +00:00
upload_concurrency:
type: integer
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: 'the number of parts to upload in parallel. If this value is set to zero, the default value (2) 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'
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:
type: integer
enum:
- 0
- 1
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
- 2
add Azure Blob support
2020-10-25 07:18:48 +00:00
- 3
add Data At Rest Encryption support
2020-12-05 12:48:13 +00:00
- 4
add sftpfs storage backend Fixes #224
2020-12-12 09:31:09 +00:00
- 5
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: |
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
Providers:
add Azure Blob support
2020-10-25 07:18:48 +00:00
* `0` - Local filesystem
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
* `1` - S3 Compatible Object Storage
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
* `2` - Google Cloud Storage
add Azure Blob support
2020-10-25 07:18:48 +00:00
* `3` - Azure Blob Storage
add Data At Rest Encryption support
2020-12-05 12:48:13 +00:00
* `4` - Local filesystem encrypted
add sftpfs storage backend Fixes #224
2020-12-12 09:31:09 +00:00
* `5` - SFTP
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
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: 'Quota as size in bytes. 0 menas unlimited, -1 means included in user quota. Please note that quota is updated if files are added/removed via SFTPGo otherwise a quota scan or a manual quota update is needed'
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
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +00:00
description: 'Quota as number of files. 0 menas unlimited, , -1 means included in user quota. Please note that quota is updated if files are added/removed via SFTPGo otherwise a quota scan or a manual quota update is needed'
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 WebDAV support Fixes #147
2020-08-11 21:56:10 +00:00
description: mapping between virtual SFTPGo paths and filesystem paths outside the user home directory. Supported for local filesystem only. If one or more of the specified folders are not inside the dataprovider they will be automatically created. You have to create the folder on the filesystem yourself
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
add WebDAV support Fixes #147
2020-08-11 21:56:10 +00:00
description: Quota as size in bytes. 0 menas unlimited. Please note that quota is updated if files are added/removed via SFTPGo otherwise a quota scan or a manual quota update is needed
first version
2019-07-20 10:26:52 +00:00
quota_files:
type: integer
format: int32
add WebDAV support Fixes #147
2020-08-11 21:56:10 +00:00
description: Quota as number of files. 0 menas unlimited. Please note that quota is updated if files are added/removed via SFTPGo otherwise a quota scan or a manual quota update is needed
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
format: int32
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
format: int32
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'
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
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 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'
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
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 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: |
* `0` - clear or explicit TLS * `1` - explicit TLS required * `2` - implicit TLS
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
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
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
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
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'
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:
$ref: '#/components/schemas/APIKey'
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
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
OpenAPI: improve schema Fix some lint warnings
2021-03-06 16:08:24 +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