alterAccount

Alter an existing account

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

 

Request examples

Maximal

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

Minimal

{
  "action": "alterAccount",
  "params": {
    "username": "AccountToBeAltered",
    "password": "NewPasswordForSpecifiedAccount"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Properties

Request properties ("params")

Property Description Default Type Limits (inclusive)

accountDescription

The "accountDescription" property defines the 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.
 Optional with default of "" string 0 to 65,500 bytes

disableDatetime

The "disableDatetime" property specifies 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.
 Optional with default of "" date Any date after "0336-10-07"

enableDatetime

The "enableDatetime" property specifies the first date and time that the account can log into the server. It is useful when you want to set 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.
 Optional with default of "" date Any date after "0336-10-07"

lockoutAfterNFailedAttempts

The "lockoutAfterNFailedAttempts" property specifies 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.
 Optional with default of the session's "LOGON_FAIL_LIMIT" property integer 0 to 2147483647

maxDaysBeforePasswordMustChange

The "maxDaysBeforePasswordMustChange" property 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.
 Optional with default of "" integer 0 to 2147483647

maxMinutesBeforeNextLogin

The "maxMinutesBeforeNextLogin" property 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 0, 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.
 Optional with default of the session's "LOGON_MUST_TIME" property integer 0 to 35791394

memoryLimit

The "memoryLimit" property 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.
 Optional with default of the session's "USR_MEMORY" property integer 0 to 2147483647

memoryRule

The "memoryRule" property uses one of the following values to specify additional rules that allow the account to exceed the memory limit defined by the "memoryLimit" property:

  1. "default"
  2. "absolute" sets the memory limit to no more than the value defined in "memoryLimit".
  3. "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.
 Optional with default of the session's "USR_MEM_RULE" property string

"default"

"absolute"

"guideline"

password

The "password" property is a user-defined password that the server uses 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.

Optional with default of "".

Required for the "createSession" action

 string 0 to 256 bytes

username

The "username" property specifies the name that uniquely identifies the account. 

 

In "alter" actions, this property specifies the account that will be altered.

 

In Key-Value actions, the "username" property is optionally used with the user keystore. It allows an administrator account or an account with the "keyValueAdmin" privilege to manage a key-value pair for another account; otherwise, the server automatically uses the session's account. This approach ensures that an ordinary account can only set and retrieve its own key-value pairs.


Within the User keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.
 

Required - No default value

 

Optional with default of the account name of the currently logged-in user for Key-Value actions

 

 string 1 to 64 bytes

 

 

Was this article helpful?

Give feedback about this article

Related Articles