# Proxmox client API

The ProxMenu client uses two HTTPS requests. It never receives Gitea
credentials.

## Exchange a deployment code

`POST https://tapm.scity.us/api/v1/exchange`

```json
{
  "code": "TAPM-ABCDE-FGHIJ",
  "host_fingerprint": "sha256-of-the-host-machine-id",
  "hostname": "pve01",
  "requested_action": "install-rmm",
  "requested_package": ""
}
```

Successful response:

```json
{
  "session_token": "opaque-session-token",
  "expires_at": "2026-07-25T23:30:00Z",
  "packages": [
    {
      "slug": "sentinelone-linux",
      "display_name": "SentinelOne Linux Agent",
      "version": "26.1.1.31",
      "sha256": "64-lowercase-hexadecimal-characters",
      "download_url": "https://tapm.scity.us/api/v1/packages/sentinelone-linux"
    }
  ],
  "actions": [
    "install-rmm",
    "install-acronis",
    "install-screenconnect"
  ]
}
```

The first exchange enrolls that host against the authorization. Reusing the
same code and host fingerprint does not consume another host slot. A different
fingerprint consumes one slot until the configured limit is reached.
When `requested_action` or `requested_package` is present, the broker validates
that entitlement before enrolling the host. Older clients may omit both fields,
but current clients should always identify what they intend to use.

An installer must proceed only when its required package slug or action slug is
present in this response. The current action slugs are:

- `install-rmm`
- `install-acronis`
- `install-screenconnect`

## Download a package

Send the session from the exchange:

```sh
curl --fail --location \
  --header "Authorization: Bearer SESSION_TOKEN" \
  --output /tmp/package.deb \
  'https://tapm.scity.us/api/v1/packages/sentinelone-linux'
```

The client must calculate SHA-256 after download and compare it to the value
returned by the exchange. It must delete the file and stop if the values differ.
The server also returns the expected value in `X-TAPM-SHA256`.

## Status behavior

- `400`: malformed request
- `403`: invalid, expired, revoked, or exhausted authorization
- `429`: too many failed exchanges from the source address; retry after the
  `Retry-After` interval
- `502`: private package registry unavailable

Codes and sessions expire at the same authorization deadline. Revoking an
authorization immediately invalidates all of its sessions.