Manage password policies

A password policy sets how long and how complex a web password must be, when it expires and when an idle login is blocked. Customers, accounts and vendors each have a Password Policy. These methods manage the policies themselves, the same as System Management → Password Policies in the panel. To check a password against a policy, use validatePassword.

Only the root customer may call these methods. They return status set to OK, not result.

Policy structure

listPasswordPolicies returns the policies as structs with these members. addPasswordPolicy and updatePasswordPolicy take the same names.

Name	Type	Description
i_password_policy	int	ID of the policy
name	string	Name of the policy, up to 64 characters
description	string	Free text
min_length	int	Min Length: the minimum length of a password, 1 to 32
i_password_content	int	Password Content, see the table below
change_first_login	boolean	Change on First Login: the user must set a new password at the first login
immutable	boolean	Immutable: users cannot change their own password
expires	int	Expires, days: a password expires this many days after it was set. None for never
block_idle_in	int	Block Idle In, days: a login not used for this many days is blocked. None for never
system	boolean	True for a built-in policy, such as Default. Only use_as_default can change; it cannot be deleted
use_as_default	boolean	Default: the policy is preselected for new customers, accounts and vendors. Only one policy is the default
i_customer	int	Customer the policy belongs to. None for policies that every customer can select, which includes all policies added with addPasswordPolicy
in_use	int	Number of customers, accounts and vendors that use the policy. Returned by listPasswordPolicies only

Password content

i_password_content	Panel label	A password must contain
1	Letters and Digits	At least one letter and one digit
2	Letters	At least one letter
3	Digits	At least one digit
4	Any Characters	No requirement

listPasswordPolicies

Lists all password policies: the built-in ones first, then the others by name.

Parameters

None.

Returns

Name	Type	Description
status	string	OK
policies	array	The policies, see the policy structure

Example

request

call("listPasswordPolicies", {})

response

{
    "status": "OK",
    "policies": [
        {
            "i_password_policy": 1,
            "name": "Default",
            "description": "",
            "min_length": 7,
            "i_password_content": 1,
            "change_first_login": True,
            "immutable": False,
            "expires": 90,
            "block_idle_in": 90,
            "system": True,
            "use_as_default": False,
            "i_customer": None,
            "in_use": 1250,
        },
        {
            "i_password_policy": 4,
            "name": "Staff",
            "description": "Customers and vendors",
            "min_length": 12,
            "i_password_content": 4,
            "change_first_login": True,
            "immutable": False,
            "expires": None,
            "block_idle_in": 30,
            "system": False,
            "use_as_default": True,
            "i_customer": None,
            "in_use": 18,
        },
    ],
}

addPasswordPolicy

Adds a password policy.

Parameters

Name	Type	Required	Description
name	string	yes	Name of the policy, up to 64 characters
description	string	no	Free text
min_length	int	no	Minimum length, 1 to 32. Default 7
i_password_content	int	no	Password content. Default 1, letters and digits
change_first_login	boolean	no	Force a new password at the first login. Default True
immutable	boolean	no	Forbid users to change their password. Default False
expires	int	no	Days until a password expires, 1 or more. Leave it out for never
block_idle_in	int	no	Days of inactivity until a login is blocked, 1 or more. Leave it out for never
use_as_default	boolean	no	Make this the default policy. The previous default policy loses the flag. Default False

Returns

Name	Type	Description
status	string	OK
i_password_policy	int	ID of the new policy

Example

request

call("addPasswordPolicy", {
    "name": "Staff",
    "description": "Customers and vendors",
    "min_length": 12,
    "i_password_content": 4,
    "block_idle_in": 30,
    "use_as_default": True,
})

response

{"status": "OK", "i_password_policy": 4}

updatePasswordPolicy

Changes a password policy. Members you do not send keep their values. Of a built-in policy (system is True) only use_as_default changes; the other members are ignored without a fault.

Parameters

Name	Type	Required	Description
i_password_policy	int	yes	ID of the policy
name, description, min_length, i_password_content, change_first_login, immutable, use_as_default		no	As in addPasswordPolicy
expires	int	no	Days until a password expires. 0 for never
block_idle_in	int	no	Days of inactivity until a login is blocked. 0 for never

Returns

Name	Type	Description
status	string	OK
i_password_policy	int	ID of the policy

Example

request

call("updatePasswordPolicy", {"i_password_policy": 4, "expires": 180, "block_idle_in": 0})

response

{"status": "OK", "i_password_policy": 4}

deletePasswordPolicy

Deletes a password policy. A built-in policy and a policy that a customer, an account or a vendor still uses cannot be deleted; move them to another policy first.

Parameters

Name	Type	Required	Description
i_password_policy	int	yes	ID of the policy

Returns

Name	Type	Description
status	string	OK
i_password_policy	int	ID of the deleted policy

Example

request

call("deletePasswordPolicy", {"i_password_policy": 4})

response

{"status": "OK", "i_password_policy": 4}

Errors

faultCode	faultString	Cause
400	i_password_policy is required and must be an integer., … must be an integer.	An ID is missing, or an integer member is not a number
400	"Name" field is required., "Name" field is too long.	name is empty or longer than 64 characters
400	"Minimal Length" must be between 1 and 32.	Wrong min_length
400	"Password Content" field has incorrect value.	i_password_content is not 1 to 4
400	"Expires" must be a positive number of days., "Block Idle In" must be a positive number of days.	A negative value, or 0 in addPasswordPolicy. Leave the member out for never
401	You do not have permissions to use this API call.	The authenticated customer is not the root customer
403	System password policies cannot be deleted.	deletePasswordPolicy was called for a built-in policy
404	Password policy not found.	No policy with this ID
409	Password policy is in use by … object(s) and cannot be deleted.	Customers, accounts or vendors still use the policy. Change their Password Policy first
500	Cannot update password policy.	The policy changed at the same time, for example in the panel. Retry

Related

• Validate a password: validatePassword
• Security management: password policies in the panel
• Customers and Accounts: the Password Policy field