# DWH REST client enrollment

The `dwh-auth` credential belongs to one ThothII installation and is needed only when the
workspace uses the `rest_api` transport.

| Trasporto | Materiale richiesto |
| --- | --- |
| `rest_api` | URL HTTPS, `API_KEY_FILE`, eventuale `TLS_CA_FILE` |
| `postgres_direct` | Credenziali PostgreSQL e configurazione TLS PostgreSQL |
| `ssh_tunnel` | Credenziali PostgreSQL e materiale SSH |

## Delivery and storage

Receive the key and CA through separate protected channels. Store the key in the installation
vault or in a regular file accessible only to the authorized account. Do not put it in Git, YAML
files, arguments, logs, or shared screens.

## ACME Limited configuration

Esempio di binding headless per il workspace `acme-ebikes`:

```dotenv
THT_WS_ACME_EBIKES_DWH_TRANSPORT=rest_api
THT_WS_ACME_EBIKES_DWH_BASE_URL=https://dwh.acme.example/dwh/
THT_WS_ACME_EBIKES_DWH_API_KEY_FILE=/run/secrets/acme-ebikes-dwh-api-key
THT_WS_ACME_EBIKES_DWH_TLS_CA_FILE=/run/secrets/acme-ebikes-dwh-ca.pem
```

The workspace suffix comes from the immutable ID, with hyphens changed to underscores and letters
converted to uppercase. `API_KEY_FILE` contains the mounted file path, not the key value.

## Rotation and revocation

During rotation, receive the new generation, update the vault or mounted file, and confirm
connectivity through the harmless `/rpc/ping` route. The server owner revokes the previous
generation only after this confirmation.

A `401` means the key is missing, unknown, expired, or revoked. A `503` means the authorization
service or registry is unavailable. In either case, do not bypass REST or weaken TLS verification.