Skip to main content

User

Overview​

Core User API implementation.

Supported actions:

  • Getters :

    • Get all users
    • Password policies
    • Password expiry

  • Setters :

    • Set user password policy

  • Actions :

    • Create new user
    • Modify user
    • Delete user
    • User join/leave group

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 a 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, optional
Defaults to False.

password_must_change bool, optional
Defaults to False.

exclude_username bool, optional
Defaults to True.

included_numeric_char bool, optional
Defaults to True.

included_special_char bool, optional
Defaults to False.

min_length int, optional
Defaults to 8.

min_length_enable bool, optional
Defaults to True.

mixed_case bool, optional
Defaults to True.

exclude_common_password bool, optional
Defaults to False.

exclude_history bool, optional
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​

Issues a passowrd/session comparison 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 username 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
}