v1

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

users

Find users by username

Returns the user with the given username if it exists. For security reasons the hashed password is omitted in the response

get/users/{username}

Query parameters

confidential_datainteger

If set to 1 confidential data will not be hidden. This means that the response will contain the hash of the password and the key and additional data for secrets. If a master key is not set or an external KMS is used, the data returned are enough to get the secrets in cleartext. Ignored if the * permission is not granted.

Response

successful operation

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 response

{
  "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
    }
  }
}