Trust boundary
The desktop process may be inspected or modified. Konvoa therefore treats it as a participant that can prove possession of a key, not as the authority for account, license, subscription, or revocation state. Protected operations recheck current server records.
Keep the private device key on the client and pin the active Konvoa response public key. Never embed an application-wide shared secret in every shipped binary.
Signed request
Hash the exact request body bytes with SHA-256, hash the exact bearer-token bytes (or the empty string before login), and preserve the origin-form path and query exactly as sent. Build and sign this UTF-8 message with Ed25519:
AUTHV2-REQ
v=2
kid=<device-key-id>
app=<application-id>
appv=<strict-semver>
apph=<executable-SHA-256-lowercase-hex>
m=POST
u=/api/v2/desktop/simple/login
host=konvoa.com
rid=<UUID-v4>
ts=<Unix-seconds>
nonce=<16-random-bytes-base64url>
ath=<access-token-SHA-256-base64url>
bh=<exact-body-SHA-256-base64url>Send X-App-Id, X-App-Version, and X-App-SHA256 on every request and sign the exact same values in canonical v2. The JSON application ID must match the signed header. This prevents an intermediary from substituting an application, claiming a newer version, or replacing the client-artifact digest. Generate a new nonce and request identifier for every attempt; never retry by resending an identical signed message.
Signed response
Konvoa signs the advertised response key ID, method, unchanged path and query, HTTP status, original request identifier, server timestamp, and exact response-body hash:
AUTHV2-RESP
v=1
kid=<server-key-id>
m=POST
u=/api/v2/desktop/simple/login
status=200
rid=<original-UUID-v4>
ts=<Unix-seconds>
bh=<exact-response-SHA-256-base64url>Resolve the key ID against the release-authenticated pin set, verify the signature, and only then parse or decrypt protected content.
Session rotation
Access tokens are short-lived and bound to the authenticated context. Refresh values rotate, and reuse of an invalidated member can revoke its family. Store credentials with the operating system’s protected facility, do not print them, and clear them after logout or terminal authentication errors.
Release links
Request a file by its application-scoped ID only after authentication. Konvoa rechecks the user, device, session, subscription, and file scope, then signs metadata containing the owner-hosted public HTTP or HTTPS URL and optional SHA-256. Modern clients download from that host without forwarding Konvoa credentials; prefer HTTPS and verify the complete artifact whenever a digest is configured. Konvoa does not accept uploads or store customer release bytes. Only the retired, empty-namespace Windows integration uses the isolated transient ticket bridge described in the file-delivery documentation.
Before shipping
- Inject the application ID, strict release version, and pinned server public key through a controlled release configuration.
- Hash the exact shipped executable or application artifact for canonical v2; never accept that digest from an untrusted remote value.
- Prefer HTTPS, validate the public DNS or IPv4 destination, and never forward Konvoa credentials or request signatures to a download host.
- Label digest-less HTTP downloads as unverified, verify every configured SHA-256, and never automatically install or execute unpinned bytes.
- Persist the device private key and rotated session credentials safely.
- Bound request and response bodies, connection timeouts, and retry counts.
- Test replay, timestamp boundaries, body and application-header tampering, wrong key IDs, revoked licenses, changed links, and digest mismatches.
Download the reference clients and checksum manifest, or use the maintained C++ SDK for the full native integration.