# UMEC Gateway Agent API Reference

## Auth

Supported auth methods:

- `Cookie: gw_session=<opaque>` after `POST /login`
- `Authorization: Bearer <agent_token>`
- `Authorization: Basic <base64(username:password)>` for compatibility

Prefer Bearer tokens for agents.

### `POST /login`

Payload:

```json
{"username":"admin","password":"admin"}
```

Success returns `{"status":"ok"}` and sets `gw_session`.

### `GET /api/auth/session`

Returns auth metadata without secrets:

```json
{
  "status": "ok",
  "authenticated": true,
  "auth_type": "bearer",
  "scopes": ["read", "test", "configure"],
  "agent_token_configured": true
}
```

### `POST /api/auth/agent-token`

Requires local admin auth. Rotates the single active token.

```json
{"scopes":["read","test","configure"]}
```

The response returns the token exactly once. Do not print it in user-facing logs.

### `DELETE /api/auth/agent-token`

Requires local admin auth. Deletes the active token.

## Useful Read Endpoints

- `GET /api/status`
- `GET /api/modbus/devices`
- `GET /api/modbus/state`
- `GET /api/modbus/runtime`
- `GET /api/modbus/gateway`
- `GET /api/recovery/status`
- `GET /api/recovery/config`

## Configuration Endpoints

- `POST /api/modbus/device`
- `GET /api/modbus/device/<id>`
- `PUT /api/modbus/device/<id>`
- `DELETE /api/modbus/device/<id>`
- `PUT /api/modbus/runtime`
- `PUT /api/modbus/gateway`
- `PUT /api/modbus/gateway/routes`
- `PUT /api/recovery/config`
- `PUT /api/network/wifi`
- `PUT /api/network/ethernet`
- `PUT /api/mqtt/generic`

Read current state before writing. After writing, re-read the affected endpoint.

## Dangerous Endpoints

- `POST /update` requires `X-Gateway-Confirm: update`
- `POST /reboot` requires `X-Gateway-Confirm: reboot`
- `POST /factory-reset` requires `X-Gateway-Confirm: factory-reset`

Bearer calls also need the `dangerous` scope for successful dangerous actions.