tip

This page contains documentation for the User class and its subclasses:

• PersonMailAccount

User

Overview

Core User API implementation.

Supported methods

• Getters :
  • Retrieve groups information.
  • Retrieve user information.
  • Get the status of a join task.
  • Get the password policy.
  • Get the password expiry.
  • Get the username policy.
• Setters :
  • Create a new user.
  • Modify a user.
  • Delete a user.
  • Affect or disaffect groups to a user.
  • Set the password policy.
  • Set the password expiry.
• Actions :
  • Confirm password/session.

Methods

user_list

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
}

---

user_get

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
}

---

user_create

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
}

---

user_set

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
}

---

user_delete

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
}

---

user_group_join

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
}

---

user_group_join_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
}

---

user_password_policy_get

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
}

---

user_password_policy_set

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
    }

---

user_password_expiry_get

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
}

---

user_password_expiry_set

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
}

---

user_username_policy_get

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
}

---

PersonMailAccount

Overview

Synology Personal Mail Account API wrapper.

Methods

mail_contacts_list

List snapshot usage entries.

Internal API

SYNO.PersonMailAccount.Contacts

Returns

dict
API response from SYNO.PersonMailAccount.Contacts.

---

mail_clean

Clean/reset the remote credential verifier.

Internal API

SYNO.PersonMailAccount.Mail

Returns

dict
API response from SYNO.PersonMailAccount.Mail.

---

mail_send

Send an email from the person mail account.

Internal API

SYNO.PersonMailAccount.Mail

Returns

dict
API response from SYNO.PersonMailAccount.Mail.

---

mail_status

Get snapshot usage tracking status.

Internal API

SYNO.PersonMailAccount.Mail

Returns

dict
API response from SYNO.PersonMailAccount.Mail.

---

mail_stop

Stop snapshot usage tracking.

Internal API

SYNO.PersonMailAccount.Mail

Returns

dict
API response from SYNO.PersonMailAccount.Mail.

---

mail_oauth_gmail

Configure Gmail as the person mail account.

Internal API

SYNO.PersonMailAccount.Mail.Oauth

Returns

dict
API response from SYNO.PersonMailAccount.Mail.Oauth.

---

mail_oauth_outlook

Configure Outlook as the person mail account.

Internal API

SYNO.PersonMailAccount.Mail.Oauth

Returns

dict
API response from SYNO.PersonMailAccount.Mail.Oauth.

---