FIfiles
users
Users

List Users

Changed on

List Users

get/users

Request

  • Base URL
    https://app.files.com/api/rest/v1
  • URL
    https://app.files.com/api/rest/v1/users
  • Auth
    none declared

Query parameters

cursorstring

Used for pagination. When a list request has more records available, cursors are provided in the response headers X-Files-Cursor-Next and X-Files-Cursor-Prev. Send one of those cursor value here to resume an existing list from the next available record. Note: many of our SDKs have iterator methods that will automatically handle cursor-based pagination.

per_pageinteger

Number of records to show per page. (Max: 10000, 1,000 or less is recommended).

If set, sort records by the specified field in either asc or desc direction. Valid fields are site_id, workspace_id, company, name, disabled, authenticate_until, username, email, site_admin, last_desktop_login_at, last_login_at, password_validity_days or ssl_required.

If set, return records where the specified field is equal to the supplied value. Valid fields are username, name, email, company, site_admin, password_validity_days, ssl_required, last_login_at, authenticate_until, not_site_admin, disabled, partner_id, primary_group_id or workspace_id. Valid field combinations are [ site_admin, username ], [ not_site_admin, username ], [ workspace_id, username ], [ company, name ], [ workspace_id, name ], [ workspace_id, email ], [ workspace_id, company ], [ workspace_id, site_admin ], [ workspace_id, not_site_admin ], [ workspace_id, disabled ], [ workspace_id, partner_id ], [ workspace_id, site_admin, username ], [ workspace_id, not_site_admin, username ], [ workspace_id, disabled, username ], [ workspace_id, partner_id, username ] or [ workspace_id, company, name ].

If set, return records where the specified field is greater than the supplied value. Valid fields are password_validity_days, last_login_at or authenticate_until.

If set, return records where the specified field is greater than or equal the supplied value. Valid fields are password_validity_days, last_login_at or authenticate_until.

If set, return records where the specified field is prefixed by the supplied value. Valid fields are username, name, email or company. Valid field combinations are [ company, name ].

If set, return records where the specified field is less than the supplied value. Valid fields are password_validity_days, last_login_at or authenticate_until.

If set, return records where the specified field is less than or equal the supplied value. Valid fields are password_validity_days, last_login_at or authenticate_until.

idsstring

comma-separated list of User IDs

include_parent_site_usersboolean

Include users from the parent site.

include_default_workspace_usersboolean

When scoped to a Custom Workspace, include Default Workspace users who have permissions in that Workspace. Available to Site Administrators, and to Workspace Administrators and Folder Admins in that Workspace when the site shares its Default Workspace directory with Workspaces.

searchstring

Searches for partial matches of name, username, or email.

Response

A list of Users objects.

idinteger

User ID

usernamestring

User's username

admin_group_idsinteger[]

List of group IDs of which this user is an administrator

allowed_ipsstring

A list of allowed IPs if applicable. Newline delimited

attachments_permissionboolean

If true, the user can user create Bundles (aka Share Links). Use the bundle permission instead.

api_keys_countinteger

Number of API keys associated with this user

authenticate_untilstring date-time

Scheduled Date/Time at which user will be deactivated

authentication_method'password' | 'sso' | 'none' | 'email_signup' | 'password_with_imported_hash' | 'password_and_ssh_key'

How is this user authenticated?

avatar_urlstring

URL holding the user's avatar

billableboolean

Is this a billable user record?

billing_permissionboolean

Allow this user to perform operations on the account, payments, and invoices?

bypass_site_allowed_ipsboolean

Allow this user to skip site-wide IP blacklists?

bypass_user_lifecycle_rulesboolean

Exempt this user from user lifecycle rules?

created_atstring date-time

When this user was created

dav_permissionboolean

Can the user connect with WebDAV?

disabledboolean

Is user disabled? Disabled users cannot log in, and do not count for billing purposes. Users can be automatically disabled after an inactivity period via a Site setting or schedule to be deactivated after specific date.

disabled_expired_or_inactiveboolean

Computed property that returns true if user disabled or expired or inactive.

ai_assistant_personality_idinteger

AI Assistant Personality ID assigned directly to this user, if any.

desktop_configuration_profile_idinteger

Desktop Configuration Profile ID assigned directly to this user, if any.

integration_centric_profile_idinteger

Integration Centric Profile ID assigned directly to this user, if any.

emailstring email

User email address

filesystem_layout'site_root' | 'user_root' | 'partner_root' | 'integration_centric' | 'workspace_root'

File system layout

first_login_atstring date-time

User's first login time

ftp_permissionboolean

Can the user access with FTP/FTPS?

group_idsstring

Comma-separated list of group IDs of which this user is a member

header_textstring

Text to display to the user in the header of the UI

languagestring

Preferred language

last_login_atstring date-time

User's most recent login time via any protocol

last_web_login_atstring date-time

User's most recent login time via web

last_ftp_login_atstring date-time

User's most recent login time via FTP

last_sftp_login_atstring date-time

User's most recent login time via SFTP

last_dav_login_atstring date-time

User's most recent login time via WebDAV

last_desktop_login_atstring date-time

User's most recent login time via Desktop app

last_restapi_login_atstring date-time

User's most recent login time via Rest API

last_api_use_atstring date-time

User's most recent API use time

last_active_atstring date-time

User's most recent activity time, which is the latest of most recent login, most recent API use, enablement, or creation

last_protocol_cipherstring

The most recent protocol and cipher used

lockout_expiresstring date-time

Time in the future that the user will no longer be locked out if applicable

namestring

User's full name

companystring

User's company

notesstring

Any internal notes on the user

notification_daily_send_timeinteger

Hour of the day at which daily notifications should be sent. Can be in range 0 to 23

office_integration_enabledboolean

Enable integration with Office for the web?

partner_adminboolean

Is this user a Partner administrator?

partner_idinteger

Partner ID if this user belongs to a Partner

partner_namestring

Name of the Partner if this user belongs to a Partner

password_set_atstring date-time

Last time the user's password was set

password_validity_daysinteger

Number of days to allow user to use the same password

primary_group_idinteger

Primary group ID for Group Admin scoping

public_keys_countinteger

Number of public keys associated with this user

receive_admin_alertsboolean

Deprecated. Use notify_on_all_site_warnings and granular failure notification preferences instead.

notify_on_all_site_warningsboolean

Should the user receive site warnings via email?

notify_on_all_sso_failuresboolean

Should the user receive sso/scim/ldap configuration/sync failures via email?

notify_on_all_user_security_eventsboolean

Should the user receive user security events via email?

notify_on_all_pending_work_failuresboolean

Should the user receive pending work failures via email?

notify_on_all_siem_http_destination_failuresboolean

Should the user receive siem failures via email?

notify_on_all_sync_failuresboolean

Should the user receive sync failures via email?

notify_on_all_automation_failuresboolean

Should the user receive automation failures via email?

notify_on_all_expectation_failuresboolean

Should the user receive expectation failures and misses via email?

require_2fa'use_system_setting' | 'always_require' | 'never_require'

2FA required setting. use_system_setting uses the site-wide setting, including SSO exemptions. always_require and never_require override the site-wide setting when user-level overrides are allowed.

require_login_bystring date-time

Require user to login by specified date otherwise it will be disabled.

active_2faboolean

Is 2fa active for the user?

require_password_changeboolean

Is a password change required upon next user login?

password_expiredboolean

Is user's password expired?

responsible_group_idinteger

ID of the internal Group responsible for this Partner User, overriding the Partner default.

responsible_user_idinteger

ID of the internal User responsible for this Partner User, overriding the Partner default.

readonly_site_adminboolean

Is the user an allowed to view all (non-billing) site configuration for this site?

restapi_permissionboolean

Can this user access the Web app, Desktop app, SDKs, or REST API? (All of these tools use the API internally, so this is one unified permission set.)

s3_compatible_endpoint_permissionboolean

Can the user access the S3-compatible endpoint? Defaults to true.

self_managedboolean

Does this user manage it's own credentials or is it a shared/bot user?

sftp_permissionboolean

Can the user access with SFTP?

site_adminboolean

Is the user an administrator for this site?

workspace_adminboolean

Whether the user is an administrator of their own Custom Workspace. Does not reflect administration granted through Permissions.

site_idinteger

Site ID

workspace_idinteger

ID of the Workspace the user belongs to. 0 is the Default Workspace.

default_workspace_idinteger

Workspace ID the user should land in by default when more than one Workspace is available.

skip_welcome_screenboolean

Skip Welcome page in the UI?

ssl_required'use_system_setting' | 'always_require' | 'never_require'

SSL required setting

sso_strategy_idinteger

SSO (Single Sign On) strategy ID for the user, if applicable.

externally_managedboolean

Is this user managed by a SsoStrategy?

tagsstring

Comma-separated list of Tags for this user. Tags are used for other features, such as UserLifecycleRules, which can target specific tags. Tags must only contain lowercase letters, numbers, and hyphens.

time_zonestring

User time zone

type_of_2fastring

Type(s) of 2FA methods in use, for programmatic use. Will be either sms, totp, webauthn, yubi, email, or multiple values sorted alphabetically and joined by an underscore. Does not specify whether user has more than one of a given method.

type_of_2fa_for_displaystring

Type(s) of 2FA methods in use, formatted for displaying in the UI. Unlike type_of_2fa, this value will make clear when a user has more than 1 of the same type of method.

user_rootstring

If filesystem layout is user_root, this path is the root path the user is fixed to for all interfaces. If the filesystem layout is site_root or partner_root, this acts as a root folder only for FTP and SFTP (SFTP applicability also requires a site-wide setting to be set). For partner_root layout, this path is relative to the Partner root folder for all callers and blank opts out of an additional protocol root. In this situation, this path is not applied to the API, Desktop, or Web interface.

user_homestring

Home folder for FTP/SFTP. For users with the partner_root filesystem layout, this path is relative to the Partner root folder. In all other cases, it is an absolute path. Only applies to FTP and SFTP, and not any other interface.

days_remaining_until_password_expireinteger

Number of days remaining until password expires

password_expire_atstring date-time

Password expiration datetime

Example response

[
  {
    "id": 1,
    "username": "user",
    "admin_group_ids": [
      1
    ],
    "allowed_ips": "10.0.0.0/8\n127.0.0.1",
    "attachments_permission": true,
    "api_keys_count": 1,
    "authenticate_until": "2000-01-01T01:00:00Z",
    "authentication_method": "password",
    "avatar_url": "example",
    "billable": true,
    "created_at": "2000-01-01T01:00:00Z",
    "dav_permission": true,
    "disabled": true,
    "disabled_expired_or_inactive": true,
    "ai_assistant_personality_id": 1,
    "desktop_configuration_profile_id": 1,
    "integration_centric_profile_id": 1,
    "email": "john.doe@files.com",
    "filesystem_layout": "site_root",
    "first_login_at": "2000-01-01T01:00:00Z",
    "ftp_permission": true,
    "group_ids": "example",
    "header_text": "User-specific message.",
    "language": "en",
    "last_login_at": "2000-01-01T01:00:00Z",
    "last_web_login_at": "2000-01-01T01:00:00Z",
    "last_ftp_login_at": "2000-01-01T01:00:00Z",
    "last_sftp_login_at": "2000-01-01T01:00:00Z",
    "last_dav_login_at": "2000-01-01T01:00:00Z",
    "last_desktop_login_at": "2000-01-01T01:00:00Z",
    "last_restapi_login_at": "2000-01-01T01:00:00Z",
    "last_api_use_at": "2000-01-01T01:00:00Z",
    "last_active_at": "2000-01-01T01:00:00Z",
    "last_protocol_cipher": "example",
    "lockout_expires": "2000-01-01T01:00:00Z",
    "name": "John Doe",
    "company": "ACME Corp.",
    "notes": "Internal notes on this user.",
    "notification_daily_send_time": 18,
    "office_integration_enabled": true,
    "partner_admin": true,
    "partner_id": 1,
    "partner_name": "example",
    "password_set_at": "2000-01-01T01:00:00Z",
    "password_validity_days": 1,
    "primary_group_id": 1,
    "public_keys_count": 1,
    "receive_admin_alerts": true,
    "notify_on_all_site_warnings": true,
    "notify_on_all_sso_failures": true,
    "notify_on_all_user_security_events": true,
    "notify_on_all_pending_work_failures": true,
    "notify_on_all_siem_http_destination_failures": true,
    "notify_on_all_sync_failures": true,
    "notify_on_all_automation_failures": true,
    "notify_on_all_expectation_failures": true,
    "require_2fa": "always_require",
    "require_login_by": "2000-01-01T01:00:00Z",
    "active_2fa": true,
    "require_password_change": true,
    "password_expired": true,
    "responsible_group_id": 1,
    "responsible_user_id": 1,
    "readonly_site_admin": true,
    "restapi_permission": true,
    "s3_compatible_endpoint_permission": true,
    "self_managed": true,
    "sftp_permission": true,
    "site_admin": true,
    "workspace_admin": true,
    "site_id": 1,
    "workspace_id": 1,
    "default_workspace_id": 1,
    "skip_welcome_screen": true,
    "ssl_required": "always_require",
    "sso_strategy_id": 1,
    "externally_managed": true,
    "tags": "example",
    "time_zone": "Pacific Time (US & Canada)",
    "type_of_2fa": "yubi",
    "type_of_2fa_for_display": "yubi",
    "user_root": "example",
    "user_home": "example",
    "days_remaining_until_password_expire": 1,
    "password_expire_at": "2000-01-01T01:00:00Z"
  }
]

Changes

  • 7f9f9aff39f1Revision changes
    • info

      added the new optional query request parameter include_default_workspace_users

  • 3bb8c8a06041Revision changes
    • warning

      deleted the query request parameter filter_like

    • warning

      deleted the query request parameter q[admin]

    • warning

      deleted the query request parameter q[allowed_ips]

    • warning

      deleted the query request parameter q[email]

    • warning

      deleted the query request parameter q[notes]

    • warning

      deleted the query request parameter q[password_validity_days]

    • warning

      deleted the query request parameter q[ssl_required]

    • warning

      deleted the query request parameter q[username]

    • info

      api tag Users added

    • info

      added the new optional query request parameter filter_prefix

    • info

      added the new optional query request parameter include_parent_site_users