# ACL SETUSER

> Create an ACL user, or change an existing user's passwords, state and permissions.

URL: https://docs.hotkv.com/commands/acl-setuser/

```
ACL SETUSER username [rule [rule ...]]
```

- Group: ACL
- Complexity: O(N) where N is the number of rules
- HotKV Cloud: all plans
- On-Premise: no license needed

`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](https://docs.hotkv.com/commands/acl-save/index.md).

## 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](https://docs.hotkv.com/commands/acl-cat/index.md)). |
| `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](https://docs.hotkv.com/commands/acl-getuser/index.md), [ACL DELUSER](https://docs.hotkv.com/commands/acl-deluser/index.md),
[ACL DRYRUN](https://docs.hotkv.com/commands/acl-dryrun/index.md), [ACL CAT](https://docs.hotkv.com/commands/acl-cat/index.md),
[Security: ACL](https://docs.hotkv.com/security/index.md#acl)