ACL SETUSER

ACL SETUSER creates the user if it does not exist and then applies the rules in order. On an existing user, the rules are applied on top of what it already has. If any rule is invalid, nothing changes. A new user starts off, with no passwords and no permissions (and no channels unless acl-pubsub-default is allchannels), so a typical call turns it on, gives it a password and grants what it needs.

Clients subscribed to channels the user loses are disconnected. Changes live in memory until you run ACL SAVE.

Rules

Rule	Effect
on, off	Enable or disable the user. A disabled user cannot log in, and its open connections run nothing.
>password, <password	Add or remove a password. A user can have several.
#hash, !hash	Add or remove a password by its SHA-256 hash (64 lowercase hex characters).
nopass	Accept any password (and drop the stored ones).
resetpass	Remove every password and nopass.
~pattern	Allow reading and writing keys that match the glob pattern.
%R~pattern, %W~pattern, %RW~pattern	Allow only reading, only writing, or both.
allkeys (same as ~*), resetkeys	Allow every key, or clear the key patterns.
&pattern	Allow pub/sub channels that match the pattern.
allchannels (same as &*), resetchannels	Allow every channel, or clear the channel patterns.
+command, -command	Allow or deny a command.
+command|subcommand, -command|subcommand	Allow or deny one subcommand.
+command|first-arg	Allow a command without subcommands only with this first argument (for example +select|0).
+@category, -@category	Allow or deny a category (see ACL CAT).
allcommands (same as +@all), nocommands (same as -@all)	Allow or deny every command, clearing the earlier command rules.
(rules)	Add a selector: another set of command, key and channel rules. A command runs if the user’s root rules or any selector allow it completely.
clearselectors	Remove all selectors.
sanitize-payload, skip-sanitize-payload	Accepted and shown for compatibility; they do not change what the user may do.
reset	Back to a new user: off, no passwords, keys, channels, selectors or commands.

Rule keywords are not case sensitive. A command, subcommand or category that does not exist is an error, so a typo cannot leave something allowed.

Return value

Simple string OK in RESP2 and RESP3, or an error that names the rule:

Case	Error
Invalid rule	ERR Error in ACL SETUSER modifier '<rule>': <reason>
Unknown command or category	... : Unknown command or category name in ACL
Malformed hash	... : The password hash must be exactly 64 characters and contain only lowercase hexadecimal characters
Removing a password the user does not have	... : The password you are trying to remove from the user does not exist
A key pattern after allkeys	... : Adding a pattern after the * pattern (or the 'allkeys' flag) has no effect; use 'resetkeys' first to start with an empty list of patterns
Unbalanced selector	ERR Unmatched parenthesis in acl selector starting at '<text>'
Name with spaces or control characters	ERR Usernames can't contain spaces or control characters

Examples

127.0.0.1:6379> ACL SETUSER app on >app-password ~* &* +@all -@dangerous
OK
127.0.0.1:6379> ACL SETUSER reports on >reports-password ~report:* -@all +@read
OK
127.0.0.1:6379> ACL SETUSER cacheonly on >c4che %R~cache:* -@all +get "(~jobs:* +lpush +rpop)"
OK
127.0.0.1:6379> ACL SETUSER reports +nosuchcommand
(error) ERR Error in ACL SETUSER modifier '+nosuchcommand': Unknown command or category name in ACL

Compatibility

Same rules as Redis 7 and Valkey 8, including key permissions and selectors. The error messages differ in places.

See also

ACL GETUSER, ACL DELUSER, ACL DRYRUN, ACL CAT, Security: ACL