# WG HTTP interface

Base: `https://APP.jmpkit.app/api/wg10`.
All requests: `Authorization: Bearer APP_MANAGEMENT_KEY`.
JSON mutations: `Content-Type: application/json`.

| Method and suffix | Result |
|---|---|
| PUT (base) | Enable the network, safely repeatable |
| GET (base) | Network, endpoint, relay public key, subnets, peers and status |
| DELETE (base) | Disable and permanently revoke every existing peer |
| POST /peers | Register `{name,publicKey,expiresAt?}`; returns peer and ID |
| GET /peers | `{peers:[...]}` including revoked/expired records |
| GET /peers/ID | Peer addresses, expiry and authorization state |
| GET /peers/ID/config | `{peer,config}` with a local-private-key placeholder |
| PATCH /peers/ID | Set `{expiresAt:"2026-12-01T00:00:00Z"}` or `{expiresAt:null}` |
| DELETE /peers/ID | Permanently revoke that peer |

`expiresAt` must be a future UTC timestamp or null. Omit for no peer-specific
deadline; the app lifecycle still applies. Replace sample dates if already past.
Unknown input fields are rejected. In particular: do not send `privateKey`.
All devices in one app network can reach each other; there are no per-peer port
ACLs yet. Client OS firewalls still apply.

Only full app management authority is accepted; app:read, app:operate, publishing
or lifecycle-only keys cannot administer WG. Possession of a WireGuard peer key
does not authorize management calls. A management-key rotation does not revoke
existing peers; revoke those explicitly if necessary.

## Addresses and configuration

Networks receive unique app subnets; peers get exact IPv4 /32 and IPv6 /128
addresses. A returned template has:

```ini
[Interface]
PrivateKey = <YOUR_LOCAL_PRIVATE_KEY>
Address = SERVER_ASSIGNED_IPV4/32, SERVER_ASSIGNED_IPV6/128
MTU = 1380

[Peer]
PublicKey = RELAY_PUBLIC_KEY
Endpoint = wg.jmpkit.com:51820
AllowedIPs = APP_IPV4_SUBNET, APP_IPV6_SUBNET
PersistentKeepalive = 25
```

Use returned values, not invented addresses. Register a separate keypair per peer.
Peer routes are checked by the relay, including isolation between app networks.
No host/LAN routes, arbitrary subnets or Internet default route are supported.
Your network must permit outbound UDP to the relay. Public relay transport is
currently tested over IPv4; private traffic inside the tunnel supports IPv4/IPv6.

## Lifecycle, failures and limits

`ready`/`authorized` means installed and permitted, not necessarily connected.
Use `wg show`, a private HTTP request or ping to establish live reachability.
App expiration/retirement withdraws peer authorization; renew the app before
trying again. Disabled networks may be enabled again, but old revoked peers stay
revoked. Register new keys as needed. Expired, unrevoked peers may have their
deadline extended. Private state survives worker restarts; authorization leases
are deliberately refreshed rather than restored blindly.

The gateway refreshes app leases every five seconds, capped at fifteen seconds.
Control outages therefore fail closed: prolonged loss temporarily disconnects
the network. Worker watchdogs also fail closed. Recovery requires fresh leases
and handshakes, so brief reconnection delays are expected.

- 401: management authentication needed/invalid.
- 403: wrong app or insufficient authority.
- 404: WG not enabled for this app, or unknown network/peer.
- 400: malformed input, private key supplied or invalid expiry.
- 409: duplicate key or capacity reached.
- 410: app lifecycle prevents use.
- 503: worker unavailable; inspect state before retrying mutations.

PUT enable is repeatable. POST registration is not idempotent: if a response is
lost, list peers and match your public key before trying again. Keep your generated
private key locally so that an interrupted registration can be recovered.

Current worker limits: 64 network slots per worker, 32 unrevoked peers per
network, 253 lifetime peer addresses per network. Addresses are not reclaimed yet;
revocation is not a way to reset lifetime allocation. Durable billing/usage
accounting is not integrated; do not promise priced or unlimited traffic.

Reference client docs: https://www.wireguard.com/install/ and
https://www.wireguard.com/quickstart/ .