Sign in

v1

latestOpenAPI 3.0.3AGPL-3.0-only2026-07-17120116247.0 KB
users

Update user

Updates an existing user and optionally disconnects it, if connected, to apply the new settings. The current password will be preserved if the password field is omitted in the request body. Recovery codes and TOTP configuration cannot be set/updated using this API: each user must use the specific APIs

put/users/{username}

Query parameters

disconnect0 | 1

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

Request body

idinteger
status0 | 1

status:

  • 0 user is disabled, login is not allowed
  • 1 user is enabled
usernamestring

username is unique

emailstring email
descriptionstring

optional description, for example the user full name

expiration_dateinteger

expiration date as unix timestamp in milliseconds. An expired account cannot login. 0 means no expiration

passwordstring password

If the password has no known hashing algo prefix it will be stored, by default, using bcrypt, argon2id is supported too. You can send a password hashed as bcrypt ($2a$ prefix), argon2id, pbkdf2 or unix crypt and it will be stored as is. For security reasons this field is omitted when you search/get users

public_keysstring[]

Public keys in OpenSSH format.

has_passwordboolean

Indicates whether the password is set

home_dirstring

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

uidinteger

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

gidinteger

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

max_sessionsinteger

Limit the sessions that a user can open. 0 means unlimited

quota_sizeinteger

Quota as size in bytes. 0 means unlimited. Please note that quota is updated if files are added/removed via SFTPGo otherwise a quota scan or a manual quota update is needed

quota_filesinteger

Quota as number of files. 0 means unlimited. Please note that quota is updated if files are added/removed via SFTPGo otherwise a quota scan or a manual quota update is needed

permissionsobject

hash map with directory as key and an array of permissions as value. Directories must be absolute paths, permissions for root directory ("/") are required

used_quota_sizeinteger
used_quota_filesinteger
last_quota_updateinteger

Last quota update as unix timestamp in milliseconds

upload_bandwidthinteger

Maximum upload bandwidth as KB/s, 0 means unlimited

download_bandwidthinteger

Maximum download bandwidth as KB/s, 0 means unlimited

upload_data_transferinteger

Maximum data transfer allowed for uploads as MB. 0 means no limit

download_data_transferinteger

Maximum data transfer allowed for downloads as MB. 0 means no limit

total_data_transferinteger

Maximum total data transfer as MB. 0 means unlimited. You can set a total data transfer instead of the individual values for uploads and downloads

used_upload_data_transferinteger

Uploaded size, as bytes, since the last reset

used_download_data_transferinteger

Downloaded size, as bytes, since the last reset

created_atinteger

creation time as unix timestamp in milliseconds. It will be 0 for users created before v2.2.0

updated_atinteger

last update time as unix timestamp in milliseconds

last_logininteger

Last user login as unix timestamp in milliseconds. It is saved at most once every 10 minutes

first_downloadinteger

first download time as unix timestamp in milliseconds

first_uploadinteger

first upload time as unix timestamp in milliseconds

last_password_changeinteger

last password change time as unix timestamp in milliseconds

additional_infostring

Free form text field for external systems

oidc_custom_fieldsobject

This field is passed to the pre-login hook if custom OIDC token fields have been configured. Field values can be of any type (this is a free form object) and depend on the type of the configured OIDC token fields

rolestring

Example request

{
  "public_keys": [
    "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEUWwDwEWhTbF0MqAsp/oXK1HR2cElhM8oo1uVmL3ZeDKDiTm4ljMr92wfTgIGDqIoxmVqgYIkAOAhuykAVWBzc= user@host"
  ],
  "virtual_folders": [
    {
      "filesystem": {
        "s3config": {
          "key_prefix": "folder/subfolder/"
        },
        "gcsconfig": {
          "key_prefix": "folder/subfolder/"
        },
        "azblobconfig": {
          "key_prefix": "folder/subfolder/"
        },
        "sftpconfig": {
          "buffer_size": 2
        }
      }
    }
  ],
  "permissions": {
    "/": [
      "*"
    ],
    "/somedir": [
      "list",
      "download"
    ]
  },
  "filters": {
    "allowed_ip": [
      "192.0.2.0/24",
      "2001:db8::/32"
    ],
    "denied_ip": [
      "172.16.0.0/16"
    ],
    "file_patterns": [
      {
        "allowed_patterns": [
          "*.jpg",
          "a*b?.png"
        ],
        "denied_patterns": [
          "*.zip"
        ]
      }
    ]
  },
  "filesystem": {
    "s3config": {
      "key_prefix": "folder/subfolder/"
    },
    "gcsconfig": {
      "key_prefix": "folder/subfolder/"
    },
    "azblobconfig": {
      "key_prefix": "folder/subfolder/"
    },
    "sftpconfig": {
      "buffer_size": 2
    }
  }
}

Response

successful operation

messagestring

message, can be empty

errorstring

error description if any