Skip to main content

"alterAccount"

JSON ADMIN "alterAccount" action alters an existing account

The "alterAccount" action alters an account that an application or user can use to log into the server. To receive privileges, an account is assigned to one or more roles - see the action "assignRolesToAccounts".

Request examples

{
  "api": "admin",
  "action": "alterAccount",
  "params": {
    "username": "NewAccount1"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
{
  "api": "admin",
  "action": "alterAccount",
  "params": {
    "username": "NewAccount1",
    "password": "CorrectHorseBatteryStaple",
    "accountDescription": "A description for NewAccount1",
    "enableDatetime": "2023-01-01",
    "disableDatetime": "2033-12-31",
    "lockoutAfterNFailedAttempts": 5,
    "maxDaysBeforePasswordMustChange": 365,
    "maxMinutesBeforeNextLogin": 0,
    "memoryLimit": 1048576,
    "memoryRule": "default"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "requestId": "1"
}

Use the alterAccount API action to alter an account that an application or user can use to log into the server

alterAccountalterAccountsalter accountJSON ADMIN APIjsonActionAPI action
Table 1. account property summaries

Property

Description

Default

Type

Limits (inclusive)

username

specifies the name that uniquely identifies the account

Required - No default value

string

1 to 31 bytes

password

specifies the code used to authenticate the account

""

string

0 to 63 bytes

accountDescription

describes the account

""

string

0 to 31 bytes

enableDatetime

specifies the first date and time that the account can log into the server

No default value

datetime

disableDatetime

specifies the last date and time that the account can log into the server

No default value

datetime

lockoutAfterNFailedAttempts

specifies the maximum number of consecutive times a failed login attempt can occur before the account is temporarily locked out

Defaults to the session's "LOGON_FAIL_LIMIT" property

integer

lockoutWaitMinutes

specifies the number of minutes an account remains temporarily locked out after the number of failed attempts defined by "lockoutAfterNFailedAttempts"

Defaults to the session's "LOGON_FAIL_TIME" property

integer

maxDaysBeforePasswordMustChange

specifies the maximum number of days a user can wait to change their password before the account is automatically locked out

No default value

integer

maxMinutesBeforeNextLogin

specifies the maximum number of minutes the server will wait for an account to log in again before it locks out the account

Defaults to the session's "LOGON_MUST_TIME" property

integer

0 to 35791394

memoryLimit

specifies the maximum number of bytes the server will allocate to the account

Defaults to the session's "USR_MEMORY" property

integer

memoryRule

specifies additional rules that can allow the account to exceed the memory limit defined in the "memoryLimit" property

Defaults to the session's "USR_MEM_RULE" property

enum

"default"
"absolute"
"guideline"


The "username" property is a required string up to 31 bytes long. It is the name that uniquely identifies the account.

The "password" property is an optional string up to 63 bytes long. The server uses the password to authenticate the account.

  • If omitted, a password is not set.

  • If present, the password is changed to the specified password. If it is set to an empty string, the server authenticates the account without a password. This is not recommended because it allows anyone to log into the account without supplying a password.

The "cloneDescription" property is an optional string up to 31 bytes long that specifies the "accountDescription" for the clone account.

  • If omitted or set to null, an account description is not set.

  • If present and set to a non-empty string, it is set to the new description.

  • If preset and set to an empty string, it is set to the empty string.

The "enableDatetime" property is an optional datetime. It specifies the first date and time that the account can log into the server. It is useful when you want to se a future date for automatically activating a new account.

  • If omitted or set to null, the earliest date and time a user can log in is not specified, and the account can be used immediately.

  • If present and set to a valid date, it is updated with that date.

  • If present and set to an empty string, it disables this feature, which means there is no earliest date when the account can log in.

The "disableDatetime" property is an optional datetime. It is the last date and time that the account can log into the server. It is useful when you want to set a future date for automatically deactivating an account.

  • If omitted or set to null, it is not changed.

  • If present and set to a valid date, it is updated.

  • If present and set to an empty string, it disables this feature, which means there is no final date when the account can login.

The "lockoutAfterNFailedAttempts" property is an optional integer. It is the maximum number of consecutive times a failed login attempt can occur before the account is temporarily locked out for "lockoutWaitMinutes".

  • This value overrides the server's default value for this account which is set by the configuration keyword LOGON_FAIL_LIMIT.

  • If omitted or set to null, it is not changed.

  • If present and set to a valid number, it is set to the new value.

The "lockoutWaitMinutes" property is an optional integer. It is the number of minutes an account remains temporarily locked out after the number of failed attempts defined by "lockoutAfterNFailedAttempts".

  • This value overrides the server's default value for this account, which is set by the configuration keyword LOGON_FAIL_TIME.

  • If omitted or set to null, it is not changed.

  • If present and set to a valid number, it is set to the new value.

The "maxDaysBeforePasswordMustChange" property is an optional integer that specifies the maximum number of days a user can wait to change their password before the account is automatically locked out. A value of zero disables this feature.

  • If omitted or set to null, it is not changed.

  • If present and set to a valid number, it is set to the new value.

The "maxMinutesBeforeNextLogin" property is an optional integer >= 0 and <= 35,791,394 that specifies the maximum number of minutes the server will wait for an account to log in again before it locks the account out. The default value is zero, which disables this feature. It is useful for automatically disabling an account due to inactivity. For example, a value of 10080 minutes requires a user to log in at least once a week.

  • This value overrides the server's default value for this account, which is set by the configuration keyword LOGON_MUST_TIME.

  • If omitted or set to null, it is not changed.

  • If present and set to a valid number, it is set to the new value.

The "memoryLimit" property is an optional integer that specifies the maximum number of bytes the server will allocate to the account. Depending on the memory rule, it may override the default memory allocations set for each user by the server for all accounts or by a group for all its accounts.

  • If omitted or set to null, it is not changed.

  • If present and set to a valid number it is set to the new value.

The "memoryRule" property is an optional enumerated string with one of the following values:

"default"
"absolute" sets the memory limit to no more than the value defined in "memoryLimit".
"guideline" allows the server to allocate additional memory while attempting to keep memory below "memoryLimit".
  • If omitted or set to null, it is not changed.

  • If present and set to a valid string, it is updated.