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.scity.us/api/v1/exchange

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

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.scity.us/api/v1/packages/sentinelone-linux"
    }
  ]
}

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.

Download a package

Send the session from the exchange:

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.