Skip to main content

User

Overview​

Core User API implementation.

Methods​

get_users(offset=0, limit=-1, sort_by="name", sort_direction="ASC", additional=[]) Retrieve groups information. get_user(name, additional=[]) Retrieve user information. create_user(...) Create a new user. modify_user(...) Modify a user. delete_user(name) Delete a user. affect_groups(name, join_groups=[], leave_groups=[]) Affect or disaffect groups to a user. affect_groups_status(task_id) Get the status of a join task. get_password_policy() Get the password policy. set_password_policy(...) Set the password policy. get_password_expiry() Get the password expiry. set_password_expiry(...) Set the password expiry. password_confirm(password) Confirm password/session. get_username_policy() Get the username policy.

Examples​

See individual method docstrings for usage examples.

Methods​

get_users​

Retrieve groups information.

Internal API​

SYNO.Core.User

Parameters​

offset int
The offset of the groups to retrieve. Defaults to 0.

limit int
The maximum number of groups to retrieve. Defaults to -1.

sort_by str
Sort by a specific field. Defaults to "name".

sort_direction str
The sort direction. Defaults to "ASC" else "DESC".

additional list[str]
Additional fields to retrieve. Defaults to []. All fields known are: ["description","email","expired","cannot_chg_passwd","passwd_never_expire","password_last_change", "groups", "2fa_status"].

Returns​

dict[str, object]
A dictionary containing the groups information.

Example return​

Click to expand
{
    "data": {
        "offset": 0,
        "total": 5,
        "users": [
        {
            "description": "System default user",
            "email": "",
            "expired": "now",
            "name": "admin",
            "passwd_never_expire": true
        },
        {
            "description": "Guest",
            "email": "",
            "expired": "now",
            "name": "guest",
            "passwd_never_expire": true
        },
        {
            "description": "",
            "email": "",
            "expired": "normal",
            "name": "test_api",
            "passwd_never_expire": true
        },
        {
            "description": "test description",
            "email": "testemail@test.com",
            "expired": "normal",
            "name": "test_user",
            "passwd_never_expire": true
        }
        ]
    },
    "success": true
}

get_user​

Retrieve user information.

Internal API​

SYNO.Core.User

Parameters​

name str
The name of the user.

additional list[str]
Additional fields to retrieve. Defaults to []. All fields known are: ["description","email","expired","cannot_chg_passwd","passwd_never_expire","password_last_change","is_password_pending"].

Returns​

dict[str, object]
A dictionary containing the user information.

Example return​

Click to expand
{
    "api": "SYNO.Core.User",
    "data": {
        "users": [
            {
                "cannot_chg_passwd": false,
                "description": "",
                "email": "",
                "expired": "normal",
                "is_password_pending": false,
                "name": "test_api",
                "passwd_never_expire": true,
                "password_last_change": 19789,
                "uid": 1027
            }
        ]
    },
    "method": "get",
    "success": true,
    "version": 1
}

create_user​

Create a new user.

Internal API​

SYNO.Core.User

Parameters​

name str
The name of the user.

password str
The password of the user.

description str
The description of the user. Defaults to "".

email str
The email of the user. Defaults to "".

expire str
The expiration date of the user. Defaults to "never".

cannot_chg_passwd bool
Whether the password can be changed. Defaults to False.

passwd_never_expire bool
Whether the password should never expire. Defaults to True.

notify_by_email bool
Whether to notify by email. Defaults to False.

send_password bool
Whether to send the password. Defaults to False.

Returns​

dict[str, object]
A dictionary containing the user information.

Example return​

Click to expand
{
    "data":
    {
        "name":"toto",
        "uid": 1030
    },
    "success": true
}

modify_user​

Modify a user.

Internal API​

SYNO.Core.User

Parameters​

name str
The name of the actual user.

new_name str
The new name of the user.

password str
The password of the user. Defaults to "".

description str
The description of the user. Defaults to "".

email str
The email of the user. Defaults to "".

expire str
The expiration date of the user. Defaults to "never".

cannot_chg_passwd bool
Whether the password can be changed. Defaults to False.

passwd_never_expire bool
Whether the password should never expire. Defaults to True.

notify_by_email bool
Whether to notify by email. Defaults to False.

send_password bool
Whether to send the password. Defaults to False.

Returns​

dict[str, object]
A dictionary containing the user information.

Example return​

Click to expand
{
    "data":{
        "name": "test_user2",
        "password_last_change": 20106,
        "uid": 1028
    },
    "success": true
}

delete_user​

Delete a user.

Internal API​

SYNO.Core.User

Parameters​

name str
The name of the user to delete.

Returns​

dict[str, object]
A dictionary containing the user information.

Example return​

Click to expand
{
    "data": {
        "name": "toto",
        "uid": 1030
    },
    "success": true
}

affect_groups​

Affect or disaffect groups to a user.

tip

This request is asynchronous and will return a task id to check the status of the join task. Use affect_groups_status func to check the status of the task.

Internal API​

SYNO.Core.User.Group

Parameters​

name str
The name of the user.

join_groups list[str]
The names of the groups to join.

leave_groups list[str]
The names of the groups to leave.

Returns​

dict[str, object]
A dictionary containing the task id to check the status of the join task. Use affect_groups_status func to check the status of the task.

Example return​

Click to expand
{
    "api": "SYNO.Core.User.Group",
    "data": {
        "task_id": "@administrators/groupbatch1737238746C6723E33"
    },
    "method": "join",
    "success": true,
    "version": 1
}

affect_groups_status​

Get the status of a join task.

Internal API​

SYNO.Core.User.Group

Parameters​

task_id str
The task id of the join task.

Returns​

dict[str, object]
A dictionary containing the status of the join task.

Example return​

Click to expand
{
    "data": {
        "auto_remove": false,
        "data": {
            "name": "test_user2",
            "pid": 18126,
            "progress": 1,
            "total": 1,
            "uid": 1028
        },
        "finish": false,
        "info": {
            "api": "SYNO.Core.User.Group",
            "group": "admin",
            "method": "join",
            "prefix": "groupbatch",
            "version": 1
        },
        "success": true
    },
    "success": true
}

get_password_policy​

Get the password policy.

Internal API​

SYNO.Core.User.PasswordPolicy

Returns​

dict[str, object]
A dictionary containing the password policy information.

Example return​

Click to expand
{
    "api": "SYNO.Core.User.PasswordPolicy",
    "data": {
        "enable_reset_passwd_by_email": false,
        "password_must_change": false,
        "strong_password": {
            "exclude_username": true,
            "history_num": 0,
            "included_numeric_char": true,
            "included_special_char": false,
            "min_length": 8,
            "min_length_enable": true,
            "mixed_case": true
        }
    },
    "method": "get",
    "success": true,
    "version": 1
}

set_password_policy​

Set the password policy.

Internal API​

SYNO.Core.User.PasswordPolicy

Parameters​

enable_reset_passwd_by_email bool
Defaults to False.

password_must_change bool
Defaults to False.

exclude_username bool
Defaults to True.

included_numeric_char bool
Defaults to True.

included_special_char bool
Defaults to False.

min_length int
Defaults to 8.

min_length_enable bool
Defaults to True.

mixed_case bool
Defaults to True.

exclude_common_password bool
Defaults to False.

exclude_history bool
Defaults to False.

Returns​

dict[str, object]
A dictionary indicating the success of the operation.

Example return​

Click to expand
    {
        "api": "SYNO.Core.User.PasswordPolicy",
        "data": {},
        "method": "set",
        "success": true,
        "version": 1
    }

get_password_expiry​

Get the password expiry.

Internal API​

SYNO.Core.User.PasswordExpiry

Returns​

dict[str, object]
A dictionary containing the password expiry information.

Example return​

Click to expand
{
    "api": "SYNO.Core.User.PasswordExpiry",
    "data": {
        "allow_reset_after_expired": true,
        "enable_login_prompt": false,
        "enable_mail_notification": false,
        "mail_notification_days": "",
        "min_age_enable": false,
        "password_expire_enable": false
    },
    "method": "get",
    "success": true,
    "version": 1
}

set_password_expiry​

Set the password expiry.

Internal API​

SYNO.Core.User.PasswordExpiry

Parameters​

password_expire_enable bool
Enable password expiry. Defaults to False.

max_age int
Maximum time before password expiry. Defaults to 30.

min_age_enable bool
Enable minimum time before password expiry. Defaults to False.

min_age int
Minimum time before password expiry. Defaults to 1.

enable_login_prompt bool
Enable login prompt. Defaults to False.

login_prompt_days int
Days before login prompt. Defaults to 1.

allow_reset_after_expired bool
Allow reset after password expiry. Defaults to True.

enable_mail_notification bool
Enable mail notification. Defaults to False.

never_expired_list list[str]
List of users that should never expire.

Returns​

dict[str, object]
A dictionary indicating the success of the operation.

Example return​

Click to expand
{
    "api": "SYNO.Core.User.PasswordExpiry",
    "method": "set",
    "success": true,
    "version": 1
}

password_confirm​

Confirm password/session to ensure the given password matches the auth of the current session.

note

This is needed by some APIs as a confirmation method, for example, when creating/modifying a scheduled task with root permissions, seldom needed by end users.

Internal API​

SYNO.Core.User.PasswordConfirm

Parameters​

password str
The password with which the session was initiated.

Returns​

dict[str, object]
A dictionary containing a SynoConfirmPWToken, or an error message.

Example return​

Click to expand
{
    "data": {
        "SynoConfirmPWToken": "xxxxx"
    },
    "success": true
}

get_username_policy​

Get the username policy (list of usernames that are not usable).

Internal API​

SYNO.Core.User.UsernamePolicy

Returns​

dict[str, object]
A dictionary containing the username policy information.

Example return​

Click to expand
{
    "api": "SYNO.Core.User.UsernamePolicy",
    "data": ["root", "rootuser", "rootusr", "admin", "administrator", "adm", "adminuser", "adminusr", "user",…],
    "method": "get",
    "success": true,
    "version": 1
}