# Users, permissions and tokens

## Users

**Administrators** may do everything, including managing users. Everyone
else gets **grants**, `resource:access`:

| Resource | read | write |
|---|---|---|
| `config` | settings, subnets, reservations, history, interfaces (the web UI shows the forms locked) | change them, undo, import |
| `leases` | leases and DHCP activity | delete a lease (making a reservation from one needs `config:write` too) |
| `audit` | the audit log | – |

The certificate (`steward cert`, Server → Certificate) is for administrators only.
| `*` | all of the above | |

**Roles** are ready-made sets of grants:

| Role | Grants |
|---|---|
| `viewer` | `config:read leases:read` |
| `operator` | `config:write leases:write audit:read` |
| `leases` | `leases:read`, e.g. for a monitoring script |

```sh
steward user add sam --role operator
steward user add monitor --no-password --role leases     # tokens only
steward user update sam --grant config:read --grant leases:write
```

The last administrator can't be removed, demoted or disabled.

## API tokens

A token has its user's permissions, or fewer. A token made with `--role`
or `--grant` can do only that, even if its user can do more:

```sh
steward token create backup-script --role leases --expires 365d
```

The secret is shown once; only its hash is stored. A restricted token can
only create tokens with a subset of its own grants. The web UI only offers
roles within what your account may do; a token with more would get no
more than its user anyway.

**Rotating** gives a token a new secret, keeping its ID, name and
permissions, so only the programs that use it need updating:

```sh
steward token rotate 7 --grace 1h           # the old secret works for another hour
steward token rotate --current --save       # this CLI's own token
```

A token that expires gets its lifetime again, from now (`--expires 90d`
or `never` to change it). Without `--grace` the old secret stops at once:
use that when it may have leaked. Using an old secret during its grace
period is logged, naming the token and the address, so you can find the
programs still to update. A restricted token may rotate itself and tokens
no wider than itself. `steward token list`
shows when each token was last used, and from where. `steward token revoke
ID` stops one at once.

## The local socket

On the server, `/run/steward/steward.sock` lets root and the `steward`
user act as administrator without a token. The audit log shows them by
their system user name. Both can already read the database, so this adds
convenience, not power. Anyone else on the socket needs a token.

## The audit log

Logins (and failed ones), users, tokens, every configuration change (with
its history entry), lease deletions and imports are recorded with who, from
where and how: `session`, `token` or `socket`.