Users

The user management syntax is available across all versions, but in the TDengine TSDB Community Edition, only basic features are functionally accessible. Advanced functionalities require the TDengine TSDB Enterprise Edition. To learn about and obtain comprehensive user management features, please contact the TDengine sales team.

Create User

CREATE USER user_name PASS 'password'
  [SYSINFO {1|0}]
  [CREATEDB {1|0}]
  [ENABLE {1|0}]
  [CHANGEPASS {2|1|0}]
  [SESSION_PER_USER {value | DEFAULT | UNLIMITED}]
  [CONNECT_TIME {value | DEFAULT | UNLIMITED}]
  [CONNECT_IDLE_TIME {value | DEFAULT | UNLIMITED}]
  [CALL_PER_SESSION {value | DEFAULT | UNLIMITED}]
  [VNODE_PER_CALL {value | DEFAULT | UNLIMITED}]
  [FAILED_LOGIN_ATTEMPTS {value | DEFAULT | UNLIMITED}]
  [PASSWORD_LOCK_TIME {value | DEFAULT | UNLIMITED}]
  [PASSWORD_LIFE_TIME {value | DEFAULT | UNLIMITED}]
  [PASSWORD_GRACE_TIME {value | DEFAULT | UNLIMITED}]
  [PASSWORD_REUSE_TIME {value | DEFAULT}]
  [PASSWORD_REUSE_MAX {value | DEFAULT}]
  [INACTIVE_ACCOUNT_TIME {value | DEFAULT | UNLIMITED}]
  [ALLOW_TOKEN_NUM {value | DEFAULT | UNLIMITED}]
  [SECURITY_LEVEL min_level, max_level]
  [HOST {ip | ip range} [, {ip | ip range}] ...]
  [NOT_ALLOW_HOST {ip | ip range} [, {ip | ip range}] ...]
  [ALLOW_DATETIME {time range} [, {time range}] ...]
  [NOT_ALLOW_DATETIME {time range} [, {time range}] ...]

The username can be up to 23 bytes long.

The password must be between 8 and 255 characters long and include at least three types of characters from the following: uppercase letters, lowercase letters, numbers, and special characters. Special characters include ! @ # $ % ^ & * ( ) - _ + = [ ] { } : ; > < ? | ~ , ., and this requirement is able to be closed by adding enableStrongPassword 0 in taos.cfg, or by the following SQL:

alter all dnodes 'EnableStrongPassword' '0'

The default values of options such as FAILED_LOGIN_ATTEMPTS are related to the configuration parameter enableAdvancedSecurity, as detailed below. The state of enableAdvancedSecurity can be changed using the following SQL.

-- enable advanced security by default
alter all dnodes 'EnableAdvancedSecurity' '1'
-- disable advanced security by default
alter all dnodes 'EnableAdvancedSecurity' '0'

SYSINFO indicates whether the user can view system information. 1 means they can view, 0 means they have no permission to view. System information includes service configuration, dnode, vnode, storage, etc. The default value is 1.
CREATEDB indicates whether the user can create databases. 1 means they can create databases, 0 means they have no permission to create databases. The default value is 0. // Supported starting from TDengine Enterprise version 3.3.2.0
ENABLE indicates whether the user is enabled, 1 means enabled, 0 means disabled. A disabled user cannot connect to the database. The default value is 1.
CHANGEPASS indicate whether the use can or must change password, 2 means can change password, 1 means must change password, 0 means cannot change password. The default value is 2. Support in Enterprise Edition v3.4.0.0 and above.
SESSION_PER_USER The maximum allowed simultaneous connections of the user. Default is 32 when enableAdvancedSecurity is 1, otherwise -1 (UNLIMITED). Minimum 1; set to -1 or UNLIMITED to disable the restriction. Support in Enterprise Edition v3.4.0.0 and above.
CONNECT_TIME The maximum allowed duration for a single session in minutes. Default is 480 when enableAdvancedSecurity is 1, otherwise -1 (UNLIMITED). Minimum 1; set to -1 or UNLIMITED to disable the restriction. Support in Enterprise Edition v3.4.0.0 and above.
CONNECT_IDLE_TIME The maximum allowed idle duration for a single session in minutes. Default is 30 when enableAdvancedSecurity is 1, otherwise -1 (UNLIMITED). Minimum 1; set to -1 or UNLIMITED to disable the restriction. Support in Enterprise Edition v3.4.0.0 and above.
CALL_PER_SESSION The maximum allowed number of sub-calls per session. Default is 128 when enableAdvancedSecurity is 1, otherwise -1 (UNLIMITED). Minimum 1; set to -1 or UNLIMITED to disable the restriction. Support in Enterprise Edition v3.4.0.0 and above.
VNODE_PER_CALL The maximum number of vnodes that a single call can involve. The default value is -1, which means unlimited. Support in Enterprise Edition v3.4.0.0 and above.
FAILED_LOGIN_ATTEMPTS The number of allowed consecutive failed login attempts; the user will be locked after exceeding this limit. The default value is 3 when enableAdvancedSecurity is 1 and UNLIMITED otherwise, with a minimum of 1, set to UNLIMITED disables the restriction. Support in Enterprise Edition v3.4.0.0 and above.
PASSWORD_LOCK_TIME The unlock waiting time for the user when locked due to failed login attempts, in minutes. The default value is 1440 when enableAdvancedSecurity is 1 and 1 otherwise, with a minimum of 1, set to UNLIMITED means the user is locked forever. Support in Enterprise Edition v3.4.0.0 and above.
PASSWORD_LIFE_TIME Password validity period, in days. The default value is 90 when enableAdvancedSecurity is 1 and UNLIMITED otherwise, with a minimum of 1, set to UNLIMITED means never expire. Support in Enterprise Edition v3.4.0.0 and above.
PASSWORD_GRACE_TIME The grace period after password expiration, in days. This is a buffer time allowing password changes, during this period, all operations other than password modification are prohibited. If the password is not changed within the grace period, the user will be locked. The default value is 7 when enableAdvancedSecurity is 1 and UNLIMITED otherwise, with a minimum of 0, set to UNLIMITED means never lock the user. Support in Enterprise Edition v3.4.0.0 and above.
PASSWORD_REUSE_TIME The duration during which an old password cannot be reused, in days. A new password must comply with both the PASSWORD_REUSE_TIME and PASSWORD_REUSE_MAX restrictions. The default value is 30 when enableAdvancedSecurity is 1 and 0 otherwise, with a maximum of 365 and a minimum of 0. Support in Enterprise Edition v3.4.0.0 and above.
PASSWORD_REUSE_MAX The number of password changes required before an old password can be reused. A new password must comply with both the PASSWORD_REUSE_TIME and PASSWORD_REUSE_MAX restrictions. The default value is 5 when enableAdvancedSecurity is 1 and 0 otherwise, with a maximum of 100 and a minimum of 0. Support in Enterprise Edition v3.4.0.0 and above.
INACTIVE_ACCOUNT_TIME User inactivity lockout period, in days. The default value is 90 when enableAdvancedSecurity is 1 and UNLIMITED otherwise, with a minimum of 1, set to UNLIMITED means never lockout the user. Support in Enterprise Edition v3.4.0.0 and above.
ALLOW_TOKEN_NUM The maximum allowed number of tokens. The default value is 3, with a minimum of 0, set to UNLIMITED disables this restriction. Support in Enterprise Edition v3.4.0.0 and above.
SECURITY_LEVEL User security level range (min_level, max_level) for Mandatory Access Control (MAC). See Mandatory Access Control (MAC). Support in Enterprise Edition.
HOST and NOT_ALLOW_HOST IP address whitelist and blacklist. Entries can be a single IP address, such as 192.168.1.1, or a subnet range in CIDR format, such as 192.168.1.1/24. Support in Enterprise Edition v3.4.0.0 and above. They take effect only when enableWhiteList is set to 1 (see taosd). For combination semantics, add/drop/query examples, and notes, see IP Allowlist and Blocklist.
ALLOW_DATETIME and NOT_ALLOW_DATETIME Permitted and prohibited login time ranges based on the server's local time zone. A valid time range consists of three parts: date, start time (accurate to the minute), and duration (in minutes). The date can be a specific date or represented by MON, TUE, WED, THU, FRI, SAT, SUN, for example: 2025-12-25 08:00 120, TUE 08:00 120. Support in Enterprise Edition v3.4.0.0 and above.
- If neither ALLOW_DATETIME nor NOT_ALLOW_DATETIME is set, the user is allowed to log in at any time.
- If only ALLOW_DATETIME is set, the user is allowed to log in during that time periods, and login at other times is not allowed.
- If only NOT_ALLOW_DATETIME is set, the user is not allowed to log in during that time periods, but login at other times is allowed.
- If both ALLOW_DATETIME and NOT_ALLOW_DATETIME are set, the user can only log in during time periods that belong to ALLOW_DATETIME and do not belong to NOT_ALLOW_DATETIME. Login at any other time is not allowed.

In the example below, we create a user with the password abc123!@# who can view system information.

taos> create user test pass 'abc123!@#' sysinfo 1;
Query OK, 0 of 0 rows affected (0.001254s)

View Users

You can use the following command to view the users in the system.

SHOW USERS;

Here is an example:

taos> show users;
       name        | super | enable | sysinfo | createdb |       create_time       | totp |      allowed_host       |   allowed_datetime   |
============================================================================================================================================
 test              |     0 |      1 |       1 |        0 | 2025-12-24 18:56:20.709 |    0 | +127.0.0.1/32, +::1/128 | +ALL                 |
 root              |     1 |      1 |       1 |        1 | 2025-12-24 18:00:43.197 |    0 | +127.0.0.1/32, +::1/128 | +ALL                 |
Query OK, 2 rows in set (0.001657s)

Note that in allowed_host, if an address or subnet range is prefixed with +, it indicates a whitelist entry, allowing login from that address. If prefixed with -, it indicates a blacklist entry, disallowing login from that address. The same rule applies to allowed_datetime.

Alternatively, you can query the built-in system table INFORMATION_SCHEMA.INS_USERS to get user information.

taos> select * from information_schema.ins_users;
       name        | super | enable | sysinfo | createdb |       create_time       | totp |      allowed_host       |   allowed_datetime   |
============================================================================================================================================
 test              |     0 |      1 |       1 |        0 | 2025-12-24 18:56:20.709 |    0 | +127.0.0.1/32, +::1/128 | +ALL                 |
 root              |     1 |      1 |       1 |        1 | 2025-12-24 18:00:43.197 |    0 | +127.0.0.1/32, +::1/128 | +ALL                 |
Query OK, 2 row(s) in set (0.007383s)

Delete User

DROP USER [IF EXISTS] user_name;

Modify User Configuration

ALTER USER user_name alter_user_clause
 
alter_user_clause: {
  [PASS 'password']
  [SYSINFO {1|0}]
  [CREATEDB {1|0}]
  [ENABLE {1|0}]
  [CHANGEPASS {2|1|0}]
  [SESSION_PER_USER {value | DEFAULT | UNLIMITED}]
  [CONNECT_TIME {value | DEFAULT | UNLIMITED}]
  [CONNECT_IDLE_TIME {value | DEFAULT | UNLIMITED}]
  [CALL_PER_SESSION {value | DEFAULT | UNLIMITED}]
  [VNODE_PER_CALL {value | DEFAULT | UNLIMITED}]
  [FAILED_LOGIN_ATTEMPTS {value | DEFAULT | UNLIMITED}]
  [PASSWORD_LOCK_TIME {value | DEFAULT | UNLIMITED}]
  [PASSWORD_LIFE_TIME {value | DEFAULT | UNLIMITED}]
  [PASSWORD_GRACE_TIME {value | DEFAULT | UNLIMITED}]
  [PASSWORD_REUSE_TIME {value | DEFAULT}]
  [PASSWORD_REUSE_MAX {value | DEFAULT}]
  [INACTIVE_ACCOUNT_TIME {value | DEFAULT | UNLIMITED}]
  [ALLOW_TOKEN_NUM {value | DEFAULT | UNLIMITED}]
  [SECURITY_LEVEL min_level, max_level]
  [ADD HOST {ip | ip range} [, {ip | ip range}] ...]
  [DROP HOST {ip | ip range} [, {ip | ip range}] ...]
  [ADD NOT_ALLOW_HOST {ip | ip range} [, {ip | ip range}] ...]
  [DROP NOT_ALLOW_HOST {ip | ip range} [, {ip | ip range}] ...]
  [ADD ALLOW_DATETIME {time range} [, {time range}] ...]
  [DROP ALLOW_DATETIME {time range} [, {time range}] ...]
  [ADD NOT_ALLOW_DATETIME {time range} [, {time range}] ...]
  [DROP NOT_ALLOW_DATETIME {time range} [, {time range}] ...]
}

The following example disables the user named test:

taos> alter user test enable 0;
Query OK, 0 of 0 rows affected (0.001160s)

After you change a user's password (ALTER USER ... PASS), the server detects existing sessions that still use the old password on heartbeat and disconnects them. Subsequent requests on those connections return authentication failure (0x80000357). The connection that performed the password change is not affected. Token-authenticated connections are not subject to this mechanism.

note

Since TDengine Enterprise Edition v3.4.2.1, ALTER USER ... SYSINFO {0|1} also updates the user's SYSINFO_0/SYSINFO_1 roles; in addition, granting an elevated system role raises the SYSINFO attribute. See Linkage Between the SYSINFO Attribute and Roles.

IP Allowlist and Blocklist

IP allowlists and blocklists restrict the addresses from which a user can log in. They are managed separately from GRANT privileges. Enterprise Edition has provided allowlist capability since v3.2.0.0; HOST / NOT_ALLOW_HOST syntax is supported from v3.4.0.0. Community Edition can run add/drop/query statements, but does not enforce source IP restrictions. Set system configuration enableWhiteList to 1 for allowlists and blocklists to take effect (see taosd).

If neither HOST nor NOT_ALLOW_HOST is set, the user may log in from any address. Note: For security and convenience, when a user is created with HOST set, or with neither HOST nor NOT_ALLOW_HOST set, the system automatically adds 127.0.0.1 and ::1 to HOST. Therefore the “any address” case only appears after you drop all HOST and NOT_ALLOW_HOST entries with ALTER USER.
If only HOST is set, login is allowed only from those addresses or ranges.
If only NOT_ALLOW_HOST is set, login from those addresses or ranges is denied; other addresses are allowed.
If both are set, login is allowed only from addresses that belong to HOST and do not belong to NOT_ALLOW_HOST.

Add an IP allowlist:

CREATE USER test PASS 'taosdata1' HOST '192.168.1.0/24', '10.0.0.1';
ALTER USER test ADD HOST '192.168.2.0/24';

Add an IP blocklist:

ALTER USER test ADD NOT_ALLOW_HOST '203.0.113.5/32';

Query:

SELECT name, allowed_host FROM information_schema.ins_users;
SHOW USERS;

In allowed_host, a + prefix means allowlist (login allowed) and a - prefix means blocklist (login denied).

Drop:

ALTER USER test DROP HOST '192.168.2.0/24';
ALTER USER test DROP NOT_ALLOW_HOST '203.0.113.5/32';

Notes:

Both Community and Enterprise editions can add and query entries, but Community Edition does not enforce IP restrictions.
You can add multiple IP ranges at once; the server deduplicates only exact duplicates. For example: CREATE USER u_write PASS 'taosdata1' HOST 'iprange1','iprange2'.
127.0.0.1 is added to the allowlist by default and is visible in queries (documentation scenarios may also include ::1).
Cluster node IP sets are added to the allowlist automatically but are not visible in queries.
When taosAdapter and taosd are not on the same host, add the taosAdapter IP to the taosd allowlist manually.
In a cluster, enableWhiteList must be consistent across nodes (all false or all true); otherwise the cluster cannot start.
Allowlist changes take effect in about 1s (no more than 2s). Each change has a negligible impact on send/receive performance; after the change completes, the impact is negligible. Changes do not affect the cluster or clients whose IPs are already on the allowlist.
If you add two ranges such as 192.168.1.1/16 (A) and 192.168.1.1/24 (B), A contains B in theory, but they are not merged because the cases are complex.
Drops must match exactly. If you added 192.168.1.1/24, you must drop 192.168.1.1/24.
Only root can add or drop IP allowlist entries for other users.
Compatible with earlier versions, but rolling back from the current version to an earlier version is not supported.
x.x.x.x/32 and x.x.x.x are the same IP range and are displayed as x.x.x.x.
If the client receives 0.0.0.0/0, the allowlist is not enabled.
When the allowlist changes, clients detect it via heartbeat.
The maximum number of IPs per user is 2048.

TOTP Two-Factor Authentication

TOTP Two-Factor Authentication is a feature of TDengine TSDB Enterprise Edition, support in version v3.4.0.1 and above.

Create/Update TOTP secret

CREATE TOTP_SECRET FOR USER user_name

If the user has not yet created a TOTP secret, this command will create a TOTP secret for the user. If the user has already created a TOTP secret, this command will update the secret for the user. In either case, this command will return the newly created secret, which will only be displayed once, please save it promptly. The system will automatically enable TOTP two-factor authentication for users who have a TOTP secret.

After enabling TOTP two-factor authentication, TDengine TSDB requires the OTP to be 6 digits long and updated every 30 seconds. Please ensure to configure your TOTP generator according to these parameters; otherwise, clients may fail to log in.

For example, we can use the following command to create a TOTP secret for user test.

taos> create totp_secret for user test;
                     totp_secret                      |
=======================================================
 ERIRPLZL4ZBFTPT5BNXMVFPR4Z3PTHUWTBTCNZPOHYPYQGTD25XA |
Query OK, 1 row(s) in set (0.002314s)

Drop TOTP Secret

DROP TOTP_SECRET FROM USER user_name

This command drops the TOTP secret from the user. After the secret is dropped, the user's TOTP two‑factor authentication will be disabled.

For example, we can use the following command to drop the TOTP key from user test.

taos> drop totp_secret from user test;
Drop OK, 0 row(s) affected (0.002295s)

Token Management

Token management is a feature of TDengine TSDB Enterprise Edition, support in version v3.4.0.0 and above.

Create Token

CREATE TOKEN [IF NOT EXISTS] token_name FROM USER user_name [ENABLE {1|0}] [TTL value] [PROVIDER value] [EXTRA_INFO value]

The token_name can be up to 31 bytes long.

ENABLE indicates whether the token is enabled, 1 means enabled, 0 means disabled. A disabled token cannot be used to connect the database. The default value is 1.
TTL validity period in days, counted from creation time. Default 0 means always valid.
PROVIDER name of the token provider, can be up to 63 bytes long.
EXTRA_INFO Additional information managed by applications, can be up to 1023 bytes long.

In the following example, we create a token named test_token for the user test. Please save the token value promptly as it is only displayed once upon creation—and cannot be queried thereafter.

taos> create token test_token from user test;
                             token                               |
==================================================================
 BsyjYKxhCMntZ3pHgweCd2uV2C8HoGKn8Mvd49dRRCtzusX0P1mgqRMrG7SzUca |
Query OK, 1 row(s) in set (0.003018s)

View Tokens

You can use the following command to view tokens in the system, but depending on your privilege, you may only see tokens of your own.

SHOW TOKENS;

For example:

taos> show tokens;
    name    | user | provider | enable |       create_time       |       expire_time       | extra_info |
=========================================================================================================
 root_token | root |          |      1 | 2025-12-25 10:02:28.000 | 1970-01-01 08:00:00.000 |            |
 test_token | test |          |      1 | 2025-12-25 10:01:47.000 | 1970-01-01 08:00:00.000 |            |
Query OK, 2 row(s) in set (0.003313s)

Alternatively, you can query the built-in system table INFORMATION_SCHEMA.INS_TOKENS to get user information.

taos> select * from information_schema.ins_tokens;
    name    | user | provider | enable |       create_time       |       expire_time       | extra_info |
=========================================================================================================
 root_token | root |          |      1 | 2025-12-25 10:02:28.000 | 1970-01-01 08:00:00.000 |            |
 test_token | test |          |      1 | 2025-12-25 10:01:47.000 | 1970-01-01 08:00:00.000 |            |
Query OK, 2 row(s) in set (0.007438s)

Modify Token

ALTER TOKEN token_name [ENABLE {1|0}] [TTL value] [PROVIDER value] [EXTRA_INFO value]

When modify the validity period (TTL), new validity period starts from the time of modification.

Drop Token

DROP TOKEN [IF EXISTS] token_name;

Note that when drop a user, tokens of the user will be cascade deleted simultaneously.

Create User​

View Users​

Delete User​

Modify User Configuration​

IP Allowlist and Blocklist​

TOTP Two-Factor Authentication​

Create/Update TOTP secret​

Drop TOTP Secret​

Token Management​

Create Token​

View Tokens​

Modify Token​

Drop Token​

Support and Feedback