Konvoa
Sign inCreate account

Developer guide

A protocol designed for software running on someone else’s machine.

Use the native SDK or a reference client to sign exact request bytes, prove possession of a device key, and verify the server’s answer before trusting it.

  1. Trust boundary
  2. Signed request
  3. Signed response
  4. Session rotation
  5. Protected delivery
  6. Before shipping

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=1
kid=<device-key-id>
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>

The application identifier belongs in the JSON body and is therefore covered by bh; it is not an extra canonical line. 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.

Verify bytes, not reconstructed JSON.Re-serializing a parsed object can change spacing, escaping, numeric forms, or property order. Hash the body exactly as received.

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.

Protected delivery

Request a one-time ticket for a file only after authentication. The ticket is short-lived, mapped to one file and authorization context, and consumed atomically by the direct download request. Refuse cross-origin redirects and enforce a maximum response body before allocating memory.

Before shipping

  • Inject the application ID and pinned server public key through a controlled release configuration.
  • Require HTTPS, verify the hostname, and refuse redirects carrying credentials or signatures.
  • 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 tampering, wrong key IDs, revoked licenses, and interrupted downloads.

Download the reference clients and checksum manifest, or use the maintained C++ SDK for the full native integration.