TA-Deployment-Broker/docs/client-api.md

Proxmox client API

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

Exchange a deployment code

POST https://tapm.example.com/api/v1/exchange

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

Successful response:

{
  "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.example.com/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. Package authorizations grant access by stable package slug. The version, filename, and checksum in a response are resolved from the current package catalog when the code is exchanged; replacing a package does not require a new authorization code. 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:

curl --fail --location \
  --header "Authorization: Bearer SESSION_TOKEN" \
  --output /tmp/package.deb \
  'https://tapm.example.com/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.