API Reference

Control-plane API for the Sidecar relay fleet. Every relay POP exposes this API on port :8443 (TLS 1.3). Authentication uses Bearer tokens issued at signup or via the billing flow.

Download OpenAPI 3.0 spec Open in Swagger UI Open in Scalar

Base URLs

Region	Base URL
US East	`https://relay-us-east1.sidecar.network:8443`
US West	`https://relay-us-west.sidecar.network:8443`
US West 1	`https://relay-us-west1.sidecar.network:8443`
Canada East	`https://relay-ca-east.sidecar.network:8443`
EU West	`https://relay-eu-west.sidecar.network:8443`
EU Central	`https://relay-eu-central.sidecar.network:8443`

Authentication

Bearer token

Obtain a token at sidecar.network/signup (free tier) or via the billing flow. Pass it as an HTTP header:

Authorization: Bearer <your-token>

Tokens are opaque, relay-scoped, and carry a tier quota (peer count, IPv6 slots, optional IPv4).

Quick start with curl

Check relay health

curl https://relay-us-east1.sidecar.network:8443/v1/health

curl -X POST https://relay-us-east1.sidecar.network:8443/v1/peers \
  -H "Authorization: Bearer $SIDECAR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pubkey": "<wg-pubkey-base64>",
    "container_id": "abc123def456",
    "psk_version": "SIDECAR-PSK/v1"
  }'

Remove a peer

curl -X DELETE https://relay-us-east1.sidecar.network:8443/v1/peers/<pubkey> \
  -H "Authorization: Bearer $SIDECAR_TOKEN"

Quick start with HTTPie

https GET relay-us-east1.sidecar.network:8443/v1/health

https POST relay-us-east1.sidecar.network:8443/v1/peers \
  Authorization:"Bearer $SIDECAR_TOKEN" \
  pubkey=<wg-pubkey> container_id=abc123

Endpoints at a glance

Method	Path	Auth	Description
GET	`/v1/version`	—	Binary version + commit
GET	`/v1/health`	—	Liveness probe
GET	`/v1/status`	—	Public relay status + privacy attestation
GET	`/canary`	—	Warrant canary text
GET	`/pgp`	—	PGP public key
GET	`/v1/altcha/challenge`	—	Altcha proof-of-work challenge
POST	`/v1/signup/free`	—	Create free-tier account
POST	`/v1/auth/magic-link`	—	Request magic-link login email
POST	`/v1/auth/magic-link/verify`	—	Verify magic-link token, get session cookie
POST	`/v1/auth/logout`	—	Revoke session cookie
POST	`/v1/peers`	Bearer	Register a WireGuard peer, get IPv6 allocation
GET	`/v1/peers`	Bearer	List active peers for this token
GET	`/v1/peers/{ipv6}`	Bearer	Look up peer by IPv6 address
DELETE	`/v1/peers/{pubkey}`	Bearer	Remove a peer
POST	`/v1/peers/{peer_id}/rotate-psk`	Bearer	Rotate pre-shared key for a peer
GET	`/v1/tokens/me`	Bearer	Token quota and tier info
POST	`/v1/tokens/rotate`	Bearer	Rotate token secret
POST	`/v1/billing/tos/accept`	—	Accept Terms of Service (checkout prerequisite)
POST	`/v1/billing/checkout/create`	—	Create one-time checkout session (Hosted Card Fields)
POST	`/v1/billing/checkout/finalize`	—	Capture payment and provision token
POST	`/v1/billing/subscribe`	—	Initiate PayPal subscription
POST	`/v1/billing/cancel`	Bearer	Cancel active subscription
POST	`/v1/billing/refunds`	Bearer	Request 14-day MBG refund
POST	`/v1/account/export`	—	GDPR/CCPA data export request
POST	`/v1/account/delete`	—	Account deletion request
POST	`/v1/support/contact`	—	Support contact form

Pricing tiers

Slug	Price	Peers	IPv4	IPv6 slots
`free`	$0	3	0	basic
`micro`	$0.99/mo	1	0	2
`spark`	$4.99/mo	5	0	16
`launch`	$9.99/mo	10	0	64
`pulse`	$19.99/mo	25	0	256
`pulse_ipv4`	$29.99/mo	25	1	256
`relay`	$39.99/mo	50	1	1024
`surge`	$59.99/mo	100	1	4096

Rate limits and errors

Most endpoints are rate-limited per source IP. The free signup and magic-link endpoints share a single per-IP limiter. HTTP 429 Too Many Requests is returned when the limit is exceeded. Errors are plain text or JSON with an error field depending on the endpoint.

Post-quantum cryptography

Peer sessions use X-Wing hybrid KEM (X25519 + ML-KEM-768, IETF draft-connolly-cfrg-xwing-kem-05) for PSK derivation. Pass mlkem_ek in POST /v1/peers to enable PQ-PSK for a peer.