# 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 | 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 | – |
| `*` | 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. `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`.