86 lines
2.6 KiB
Markdown
86 lines
2.6 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",
|
|
"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.
|
|
|
|
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.
|