# IAM.ROLE.CREATE

> Create a role: a set of commands and keys that logins can be given.

URL: https://docs.hotkv.com/commands/iam-role-create/

```
IAM.ROLE.CREATE name permissions [KEY_PREFIXES prefixes] [RATE_LIMIT commands-per-second] [IP_ALLOWLIST networks]
```

- Group: IAM
- Complexity: O(N) where N is the size of the role
- HotKV Cloud: not available
- On-Premise: requires the enterprise-iam license feature

`IAM.ROLE.CREATE` defines a role. [IAM.USER.ASSIGN](https://docs.hotkv.com/commands/iam-user-assign/index.md)
gives it to users and groups, and a login that has it can run the commands the
role allows, on the keys it reaches, and nothing else. See
[Roles and single sign-on](https://docs.hotkv.com/operate/iam/index.md) for how roles are used.

The role is the same on every node of a cluster: a change made on one node
reaches the others, and it is saved with the data and replicated. A role cannot
be changed once it is made: delete it with
[IAM.ROLE.DELETE](https://docs.hotkv.com/commands/iam-role-delete/index.md) and create it again.

## Arguments

| Argument | Meaning |
| --- | --- |
| `name` | 1 to 64 characters, with no spaces or control characters |
| `permissions` | What the role allows, a list separated by commas (see below) |

`permissions` is a list of entries, and the role needs at least one that allows
something:

| Entry | Meaning |
| --- | --- |
| `get`, `config\|get` | Allow a command, or one subcommand of it |
| `@read`, `@write`, `@connection`, `@all` | Allow a category of commands (`*` is `@all`). [ACL CAT](https://docs.hotkv.com/commands/acl-cat/index.md) lists them |
| `-flushall`, `-@dangerous`, `-@admin` | Never allow a command or a category, whatever else the role allows |

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

## Options

| Option | Meaning | Default |
| --- | --- | --- |
| `KEY_PREFIXES prefixes` | The keys the role reaches, separated by commas. An entry with no `*`, `?` or `[` is a prefix (`app:` is `app:*`), one with them is a pattern. Channels follow the keys | All keys |
| `RATE_LIMIT n` | Commands per second, for all the connections of a login together | 0 (unlimited) |
| `IP_ALLOWLIST networks` | Addresses or networks (CIDR) a login must come from to have the role, separated by commas, such as `10.0.0.0/8,fd00::/8` | From anywhere |

Option names are not case sensitive.

`@write` also holds HotKV's administrative commands that change the server,
such as `IAM.USER.ASSIGN` and `TENANT.CREATE`, so a role of `@write` alone
would let its users give themselves any role. A role like that is refused
unless it removes those commands (`-@admin` or `-@dangerous`), or names
`@admin`, `@dangerous` or `@all` to say that is meant.

## Return value

Simple string `OK` in RESP2 and RESP3, or one of these errors (the role is not
created):

| Case | Error |
| --- | --- |
| The name is taken | `ERR role already exists` |
| A bad name | `ERR a role name is 1 to 64 characters, with no spaces or control characters` |
| Nothing is allowed | `ERR a role needs at least one command or @category it allows` |
| An entry with a space or a control character | `ERR a permission has a space or a control character: 'get set'` |
| A command or category that does not exist | `ERR unknown command or category 'nosuchcommand'` |
| A rate limit that is not a number | `ERR invalid RATE_LIMIT value` |
| `MEMORY_QUOTA` | `ERR MEMORY_QUOTA is not supported. Use maxmemory for the server, or tenants (TENANT.*) for separate budgets` |
| An option the command does not know | `ERR unknown option 'name'` |
| An option without a value | `ERR syntax error` |
| A key prefix that is empty or has a space | `ERR a key prefix is empty, or has a space or a control character` |
| A network that is not one | `ERR 'nonsense' is not an address or a network (10.0.0.0/8)` |
| A prefix length longer than the address | `ERR '10.0.0.0/99' has a prefix length that is longer than the address` |
| A role that would allow administration | `ERR this role would let its users run administrative commands that change the server (iam.role.create, iam.role.delete, iam.user.assign, iam.user.unassign, ...): remove them with -@admin or -@dangerous, or name @admin or @all if that is meant` |
| Fewer than two arguments | `ERR wrong number of arguments for 'iam.role.create' command` |
| No license that includes `enterprise-iam` | `NOLICENSE enterprise-iam requires a HotKV license. Contact sales@hotkv.com` |

## Examples

```
127.0.0.1:6379> IAM.ROLE.CREATE app "@read,@write,@connection,-@dangerous" KEY_PREFIXES app:
OK
127.0.0.1:6379> IAM.ROLE.CREATE reporting "get,mget,scan" KEY_PREFIXES "report:,shared:*" RATE_LIMIT 500
OK
127.0.0.1:6379> IAM.ROLE.CREATE office "@all" IP_ALLOWLIST "10.0.0.0/8,fd00::/8"
OK
127.0.0.1:6379> IAM.ROLE.CREATE app get
(error) ERR role already exists
127.0.0.1:6379> IAM.ROLE.CREATE writer "@write"
(error) ERR this role would let its users run administrative commands that change the server (iam.role.create, iam.role.delete, iam.user.assign, iam.user.unassign, ...): remove them with -@admin or -@dangerous, or name @admin or @all if that is meant
```

## Compatibility

HotKV-only command.

## See also

[IAM.USER.ASSIGN](https://docs.hotkv.com/commands/iam-user-assign/index.md), [IAM.ROLE.INFO](https://docs.hotkv.com/commands/iam-role-info/index.md),
[IAM.ROLE.DELETE](https://docs.hotkv.com/commands/iam-role-delete/index.md), [IAM.AUTH](https://docs.hotkv.com/commands/iam-auth/index.md)