API Authentication¶

WireBuddy API access is based on application sessions.

Authentication Modes¶

After login, the UI uses an auth_token cookie for authenticated API requests.

2) Bearer Header¶

Automation clients can use the same auth token in the Authorization header:

curl -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  https://vpn.example.com/api/wireguard/peers

Important:

There is currently no separate long-lived API-token subsystem.
Bearer auth validates the same session token model used by cookie auth.

How to Obtain an Auth Token¶

Use the normal login endpoint and capture the resulting session token from your client flow.

POST /api/login

For MFA-enabled users, complete the MFA verification step:

POST /api/mfa/verify

Then send requests with either cookie auth (browser-like clients) or Bearer header auth.

Node Sync Authentication¶

Node daemon synchronization routes under /api/nodes/* (for example enroll, heartbeat, config/events sync, node speedtest submit/progress) use dedicated node authentication:

POST /api/nodes/enroll is authenticated by a signed enrollment token and the node's self-signed certificate.
All later sync requests require Authorization: Bearer <node_api_secret>.
The X-Client-Cert-Fingerprint header is only evaluated when it comes from a proxy listed in WIREBUDDY_TRUSTED_PROXIES (no proxy is trusted by default for this header). Then it must match the fingerprint stored at enrollment; otherwise it is ignored and the Bearer secret is the only credential.

This is separate from user session auth.

Error Semantics¶

401 Unauthorized¶

Typical causes:

Missing auth token
Invalid token
Expired session

403 Forbidden¶

Typical causes:

Authenticated but missing admin privileges
Account disabled

429 Too Many Requests¶

Rate-limited request. Respect Retry-After when provided.

Security Recommendations¶

Use HTTPS only.
Prefer Authorization headers for non-browser automation.
Do not log tokens.
Rotate/re-authenticate automation sessions regularly.

Examples¶

Bash¶

API_URL="https://vpn.example.com/api"
TOKEN="YOUR_AUTH_TOKEN"

curl -s -H "Authorization: Bearer $TOKEN" \
  "$API_URL/wireguard/interfaces"

Python¶

import requests

api_url = "https://vpn.example.com/api"
token = "YOUR_AUTH_TOKEN"
headers = {"Authorization": f"Bearer {token}"}

resp = requests.get(f"{api_url}/wireguard/peers", headers=headers, timeout=10)
print(resp.status_code)
print(resp.json())