142 lines
4.5 KiB
Markdown
142 lines
4.5 KiB
Markdown
# 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`
|
|
|
|
```json
|
|
{
|
|
"code": "TAPM-ABCDE-FGHIJ",
|
|
"host_fingerprint": "sha256-of-the-host-machine-id",
|
|
"hostname": "pve01",
|
|
"installation_id": "123e4567-e89b-42d3-a456-426614174000",
|
|
"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.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.
|
|
Current V2 clients also send their random `installation_id`. A successful
|
|
code exchange marks the matching fleet record as verified; it does not expose
|
|
or replace the host's fleet credential.
|
|
|
|
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.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.
|
|
|
|
## Fleet registration
|
|
|
|
V2 clients register a locally generated installation identity:
|
|
|
|
`POST https://tapm.example.com/api/v1/hosts/register`
|
|
|
|
```json
|
|
{
|
|
"schema_version": 1,
|
|
"installation_id": "123e4567-e89b-42d3-a456-426614174000",
|
|
"credential": "64-lowercase-hexadecimal-characters",
|
|
"proxmenu_version": "2026.7.26-7",
|
|
"git_commit": "40-lowercase-hexadecimal-characters",
|
|
"pve_version": "pve-manager/9.0.3/abc~1",
|
|
"os_version": "Debian GNU/Linux 13 (trixie)",
|
|
"kernel_version": "6.14.11-2-pve",
|
|
"architecture": "amd64",
|
|
"clustered": false
|
|
}
|
|
```
|
|
|
|
The first request returns `201`; subsequent authenticated registrations return
|
|
`200`. The broker stores a SHA-256 digest of the 256-bit random credential, not
|
|
the credential itself. New registrations are limited per privacy-preserving
|
|
HMAC of the source address to reduce anonymous registry abuse.
|
|
|
|
## Fleet lifecycle events
|
|
|
|
`POST https://tapm.example.com/api/v1/hosts/events`
|
|
|
|
The request uses `Authorization: Bearer HOST_CREDENTIAL`. Its body has the same
|
|
schema and platform metadata as registration, omits `credential`, and adds:
|
|
|
|
```json
|
|
{
|
|
"event": "run_completed",
|
|
"result": "success",
|
|
"error_code": "",
|
|
"duration_seconds": 19
|
|
}
|
|
```
|
|
|
|
Accepted events are `run_started`, `run_completed`, `run_failed`, and
|
|
`upgraded`. Events are best-effort and are sent only while TA-ProxMenu is
|
|
running; there is no resident monitoring service.
|
|
|
|
The fleet API deliberately does not accept or store hostnames, machine IDs,
|
|
MAC addresses, usernames, customer names, VM/container inventory, deployment
|
|
tokens, or command output. The portal shows random installation IDs, first and
|
|
last activity, verification status, software/platform versions, cluster mode,
|
|
and the latest structured result.
|