API reference

Authentication

Create an API key in Settings → API keys inside the dashboard. The token is shown once, starts with vrk_, and is sent as a bearer token:

curl https://vaultroute.store/api/auth/me \
  -H "Authorization: Bearer vrk_your_token_here"

Browsers signed in to the dashboard can use the same endpoints with the session cookie instead. API keys are scoped to one customer account. There are no multi-tenant or reseller keys — each deployment has its own users, keys and data.

Conventions

• Send Content-Type: application/json on POST requests.
• Amounts are integer cents (1500 = $15.00).
• Data quantities are bytes in responses and GB in requests (1 GB = 1,000,000,000 bytes).
• Timestamps are ISO-8601 UTC strings.
• Mutating order calls accept an idempotencyKey; retrying the same key returns the original order.
• Success responses include "ok": true. Failures return an HTTP status plus { "ok": false, "error": "…", "code": "…" }.

Errors

Status	Meaning
400	Invalid input, missing acknowledgement, or a non-crypto payment method.
401	Missing or invalid credentials.
402	Prepaid balance is too low for the order.
403	Admin-only route, cross-origin browser request, or disabled account.
404	Unknown resource.
409	Conflict such as a duplicate email or an already-paid invoice.
429	Rate limited; check the Retry-After header.
502	The upstream network or payment provider could not fulfill the request.

Public endpoints

Endpoint	Description
GET /api/health	Liveness probe. No auth.
GET /api/config	Brand, retail prices, limits and payment mode.
GET /api/openapi.json	This API as an OpenAPI 3.1 document.

Accounts

Endpoint	Description
POST /api/auth/register	Create an account. Body: email, password (10+ chars), name, acceptAup: true.
POST /api/auth/login	Sign in and set the session cookie. Body: email, password.
GET /api/auth/me	Current user plus stats (balance, active lines, data balance).
POST /api/auth/logout	Destroy the current session.
POST /api/account/profile	Update name.
POST /api/account/password	Change password. Body: currentPassword, newPassword.
GET /api/account/api-keys	List keys (prefix and metadata only, never the token).
POST /api/account/api-keys	Create a key. Body: name. The token is returned once.
DELETE /api/account/api-keys/:id	Revoke a key immediately.

Dedicated IPs

Endpoint	Description
GET /api/catalog/countries	Available countries with counts and the single-IP price.
GET /api/catalog/cities?country=US	Cities for a country.
POST /api/orders/quote	Price a quantity. Body: count (1–500).
POST /api/orders	Buy IPs from the prepaid balance.
GET /api/orders	Order history.

Create an IP order. The acknowledgement is mandatory and enforced server-side:

curl -X POST https://vaultroute.store/api/orders \
  -H "Authorization: Bearer vrk_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "US",
    "city": "Chicago",
    "count": 2,
    "idempotencyKey": "order-2026-001",
    "acknowledgeShortLived": true
  }'

The response contains the order and the delivered lines. Lines are raw IP:port:username:password credentials; the upstream hostname is never exposed.

{
  "ok": true,
  "order": { "id": "ord_…", "type": "ip", "count": 2, "status": "paid", "…": "…" },
  "proxies": [
    {
      "host": "203.0.113.10",
      "port": 8000,
      "username": "…",
      "password": "…",
      "country": "US",
      "city": "Chicago",
      "expiresAt": "2026-11-11T10:00:00.000Z",
      "status": "active",
      "plan": "ip"
    }
  ],
  "reused": false
}

Bandwidth packages

Endpoint	Description
GET /api/gb/plans	GB tiers, line limits and minimum purchase.
POST /api/gb/quote	Price a package. Body: gb, lines.
POST /api/gb/orders	Buy bandwidth. Body: gb, lines, country, optional city, idempotencyKey.
GET /api/gb/orders	Bandwidth order history with per-order quotas.
GET /api/gb/usage	Combined per-customer data balance and cutoff state.
POST /api/gb/usage/refresh	Ask the server to poll usage now (throttled).
GET /api/gb/export?format=txt|csv|json	Export live bandwidth lines.

curl -X POST https://vaultroute.store/api/gb/orders \
  -H "Authorization: Bearer vrk_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "gb": 10, "lines": 3, "country": "US", "idempotencyKey": "gb-2026-001" }'

GET /api/gb/usage returns the account-level balance:

{
  "ok": true,
  "usage": {
    "quotaBytes": 10000000000,
    "usedBytes": 2500000000,
    "remainingBytes": 7500000000,
    "usedGb": 2.5,
    "remainingGb": 7.5,
    "percent": 25,
    "activeOrders": 1,
    "exhaustedOrders": 0,
    "revokedLines": 0,
    "disconnectedAt": null,
    "isolated": true
  },
  "orders": [ … ],
  "syncedAt": "2026-11-10T09:00:00.000Z"
}

Delivered lines and health

Endpoint	Description
GET /api/proxies?status=active&plan=ip|gb	Delivered lines. Omit filters for everything.
GET /api/proxies/export?format=txt|csv|json&plan=ip|gb	Download lines.
POST /api/proxies/check?plan=ip|gb	Server-side connectivity check for up to 50 active lines.

Crypto billing

Endpoint	Description
GET /api/billing/invoices	Invoice history with provider status and checkout URL.
POST /api/billing/invoices	Create a hosted crypto invoice. Body: amountCents and method: "crypto".
POST /api/billing/invoices/:id/sync	Poll the provider as a backup for a missed callback.

curl -X POST https://vaultroute.store/api/billing/invoices \
  -H "Authorization: Bearer vrk_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "amountCents": 5000, "method": "crypto" }'

{
  "ok": true,
  "invoice": {
    "id": "inv_…",
    "reference": "INV-AB12CD",
    "amountCents": 5000,
    "method": "crypto",
    "provider": "nowpayments",
    "providerStatus": "waiting",
    "paymentUrl": "https://nowpayments.io/payment/?iid=…",
    "status": "pending",
    "createdAt": "2026-11-10T09:00:00.000Z"
  },
  "checkout": { "provider": "nowpayments", "url": "https://nowpayments.io/payment/?iid=…" }
}

Send the customer to checkout.url. The wallet is credited only when the provider reports finished. Card and bank methods return 400 crypto_only. If an IPN is delayed, call the sync endpoint; completed invoices stay paid and are never credited twice.

Webhooks

The deployment receives NOWPayments IPNs at https://vaultroute.store/api/webhooks/nowpayments. The server verifies the x-nowpayments-sig HMAC-SHA512 signature with the server-side IPN secret before doing anything. This endpoint is for the payment provider only; customers do not call it.

Admin endpoints

Admin accounts can use /api/admin/overview, /api/admin/users, /api/admin/orders, /api/admin/invoices, /api/admin/settings and /api/admin/usage/sync. Admin keys are ordinary API keys on an account whose role is admin. Keep such keys on the server, never in a browser bundle.

Rate limits

Sign-in, registration, invoice creation, status polling and API-key creation are rate limited per account and IP. A limited response is 429 with Retry-After in seconds. Order calls are also serialised per user with an idempotency key to prevent double charges.

OpenAPI

The machine-readable specification is at /api/openapi.json. Import it into Postman or Swagger UI and set the bearer token as your auth variable.