// Developer Reference

OmniShield API Documentation

Public REST API for the OmniShield VPN platform. Build clients, integrations, and automation against our endpoints. Base URL: https://omnishield.io

Download OpenAPI 3.1 Setup Guide

Authentication

Most endpoints require a Bearer token. Get one with POST /api/auth/create (no email required) and pass it as Authorization: Bearer <token>. Public endpoints are marked accordingly.

# Authentication

POST/api/auth/createpublic

Create a new VPN account

Provisions a brand-new OmniShield account and returns an access token plus a VLESS subscription URL. No email or KYC required.

Request body

{
  "device_id": "string (optional, UUID)",
  "referral_code": "string (optional)"
}

Response

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user_id": 12345,
  "subscription_url": "https://omnishield.io/sub/abc123..."
}

cURL example

curl -X POST https://omnishield.io/api/auth/create \
  -H "Content-Type: application/json" \
  -d '{"device_id":"ios-uuid-here"}'

Error codes

429 — Rate limit exceeded
500 — Provisioning failed

POST/api/auth/loginpublic

Log in with an existing token

Exchanges a long-lived account token for a fresh JWT access token. Used by clients to refresh sessions.

Request body

{
  "token": "string"
}

Response

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user_id": 12345
}

cURL example

curl -X POST https://omnishield.io/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"token":"YOUR_TOKEN"}'

Error codes

401 — Invalid token
429 — Too many login attempts

# VPN

GET/api/vpn/statusauth

Get current VPN account status

Returns the active plan, expiration date, traffic used, and device count for the authenticated user.

Response

{
  "active": true,
  "plan": "premium",
  "expires_at": "2026-12-31T23:59:59Z",
  "traffic_used_gb": 14.2,
  "traffic_limit_gb": null,
  "devices": 2,
  "max_devices": 5
}

cURL example

curl https://omnishield.io/api/vpn/status \
  -H "Authorization: Bearer YOUR_JWT"

Error codes

401 — Missing or invalid token

GET/api/vpn/serverspublic

List all available VPN servers

Public list of OmniShield server locations including country, city, load, and supported protocols.

Response

[
  {
    "id": "nl-ams-1",
    "country": "NL",
    "city": "Amsterdam",
    "flag": "\ud83c\uddf3\ud83c\uddf1",
    "load": 0.32,
    "protocols": ["vless_reality", "shadowsocks", "awg"]
  }
]

cURL example

curl https://omnishield.io/api/vpn/servers

GET/api/vpn/server-statuspublic

Real-time server health

Returns current ping, packet loss, and uptime for each server. Used by the public status page.

Response

{
  "servers": [
    { "id": "nl-ams-1", "online": true, "ping_ms": 18, "uptime_pct": 99.98 }
  ],
  "updated_at": "2026-04-04T12:00:00Z"
}

cURL example

curl https://omnishield.io/api/vpn/server-status

GET/api/vpn/protocolspublic

List supported VPN protocols

Returns the catalog of protocols OmniShield supports, with description and recommended use case.

Response

[
  { "id": "vless_reality", "name": "VLESS + Reality", "port": 443, "censorship_resistant": true },
  { "id": "hysteria2", "name": "Hysteria2", "port": 2054, "censorship_resistant": true },
  { "id": "awg", "name": "AmneziaWG", "port": 51820, "censorship_resistant": true }
]

cURL example

curl https://omnishield.io/api/vpn/protocols

POST/api/vpn/smart-routepublic

Get the best server for the caller

Smart routing endpoint. Returns the optimal server + protocol combination based on the caller's IP, latency, and detected ISP blocks.

Request body

{
  "preferred_country": "NL",
  "use_case": "streaming"
}

Response

{
  "server_id": "nl-ams-1",
  "protocol": "vless_reality",
  "config_url": "vless://uuid@host:443?...",
  "expected_ping_ms": 22
}

cURL example

curl -X POST https://omnishield.io/api/vpn/smart-route \
  -H "Content-Type: application/json" \
  -d '{"use_case":"streaming"}'

GET/api/vpn/extra-protocolsauth

List premium protocol unlocks

Returns the additional protocols (AmneziaWG, DTLS, XHTTP) available to the authenticated user.

Response

{
  "awg": { "available": true, "nodes": 8 },
  "dtls": { "available": true },
  "xhttp": { "available": false }
}

cURL example

curl https://omnishield.io/api/vpn/extra-protocols \
  -H "Authorization: Bearer YOUR_JWT"

Error codes

401 — Auth required

POST/api/vpn/awg-configauth

Generate an AmneziaWG config

Provisions a new AmneziaWG peer on the requested node and returns a ready-to-import .conf file content.

Request body

{
  "node_id": "nl-ams-1"
}

Response

{
  "config": "[Interface]\nPrivateKey=...\nAddress=10.8.0.5/32\n...",
  "filename": "omnishield-nl-ams-1.conf"
}

cURL example

curl -X POST https://omnishield.io/api/vpn/awg-config \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"node_id":"nl-ams-1"}'

Error codes

401 — Auth required
404 — Node not found

GET/api/vpn/awg-nodesauth

List AmneziaWG nodes

Returns AmneziaWG endpoints available to the authenticated user.

Response

[
  { "id": "nl-ams-1", "country": "NL", "endpoint": "nl1.omnishield.io:51820" },
  { "id": "de-fra-1", "country": "DE", "endpoint": "de1.omnishield.io:51820" }
]

cURL example

curl https://omnishield.io/api/vpn/awg-nodes \
  -H "Authorization: Bearer YOUR_JWT"

POST/api/vpn/dtls-configauth

Generate a DTLS tunnel config

Provisions a DTLS-over-UDP tunnel for the user. Useful when QUIC and TCP are throttled.

Request body

{
  "node_id": "nl-ams-1"
}

Response

{
  "config": "...",
  "endpoint": "dtls://nl1.omnishield.io:4433"
}

cURL example

curl -X POST https://omnishield.io/api/vpn/dtls-config \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"node_id":"nl-ams-1"}'

# Wallet & Referrals

GET/api/wallet/balanceauth

Get wallet balance

Returns the user's current wallet balance in USD and the bonus balance from referrals.

Response

{
  "balance_usd": 12.50,
  "bonus_usd": 3.00,
  "currency": "USD"
}

cURL example

curl https://omnishield.io/api/wallet/balance \
  -H "Authorization: Bearer YOUR_JWT"

GET/api/referral/codeauth

Get the user's referral code

Returns the user's unique referral code and shareable link.

Response

{
  "code": "OMNI-AB12CD",
  "url": "https://omnishield.io/r/OMNI-AB12CD",
  "referrals_count": 3,
  "earned_usd": 9.00
}

cURL example

curl https://omnishield.io/api/referral/code \
  -H "Authorization: Bearer YOUR_JWT"

GET/api/wallet/transactionsauth

Unified deposit + refund history

Returns the most recent wallet activity. Each item has type=deposit|refund, direction=credit|debit|pending, and a signed amount_usd (negative for approved refunds). limit query clamped 1..200.

Response

{
  "transactions": [
    { "type": "deposit", "id": "...", "amount_usd": 20.00,
      "direction": "credit", "method": "usdt-trc20",
      "status": "completed", "track_id": "...",
      "created_at": "...", "completed_at": "..." },
    { "type": "refund", "id": "...", "amount_usd": -5.00,
      "direction": "debit", "status": "approved", ... }
  ],
  "count": 2,
  "balance_usd": 15.00
}

cURL example

curl "https://omnishield.io/api/wallet/transactions?limit=50" \
  -H "Authorization: Bearer YOUR_JWT"

GET/api/auth/sessionsauth

List active devices / refresh tokens

Returns every non-revoked, non-expired refresh token belonging to the caller, with last_used_ip + last_used_at so the user can spot a session they don't recognize. The is_current flag marks the row whose last_used_ip matches the caller.

Response

{
  "sessions": [
    { "id": "uuid", "created_at": "...", "last_used_at": "...",
      "last_used_ip": "1.2.3.4", "expires_at": "...",
      "is_current": true }
  ],
  "count": 1
}

cURL example

curl https://omnishield.io/api/auth/sessions \
  -H "Authorization: Bearer YOUR_JWT"

DELETE/api/auth/sessions/{id}auth

Revoke a single session

Revokes one refresh token by its DB id. Subsequent /refresh attempts with that raw token trigger the chain-revocation path and log every device out — that's the safe choice if a stolen token is suspected.

Response

{
  "ok": true,
  "id": "uuid",
  "revoked_at": "2026-05-17T18:30:00"
}

cURL example

curl -X DELETE https://omnishield.io/api/auth/sessions/SESSION_ID \
  -H "Authorization: Bearer YOUR_JWT"

Error codes

404 — Session not found (or belongs to another user — no enumeration leak)

POST/api/auth/refreshpublic

Rotate access token (with refresh)

Exchanges a valid refresh token for a new (access_token, refresh_token) pair. Old refresh is revoked on success. Reusing an old refresh triggers chain revocation — every active refresh for the user is killed.

Response

{
  "access_token": "eyJ...",
  "refresh_token": "abc123...",
  "token_type": "bearer",
  "user": { ... }
}

cURL example

curl -X POST https://omnishield.io/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"YOUR_REFRESH_TOKEN"}'

Error codes

401 — Invalid / revoked / expired refresh token (chain revocation may have fired)

POST/api/auth/logoutauth

Revoke all of the user's refresh tokens

Hard logout — every active refresh token for the user is revoked. The access token itself keeps working until its 15-min TTL expires.

Response

{ "status": "logged_out", "tokens_revoked": 3 }

cURL example

curl -X POST https://omnishield.io/api/auth/logout \
  -H "Authorization: Bearer YOUR_JWT"

# System & Subscription

GET/healthpublic

Health check

Cheap liveness probe served by the Next.js layer (no backend call). Returns 200 + timestamp. Suitable for UptimeRobot / BetterStack pings.

Response

{
  "status": "ok",
  "service": "omnishield-web",
  "ts": "2026-05-17T18:30:00.000Z"
}

cURL example

curl https://omnishield.io/health

GET/sub/{token}public

Subscription URL (Hiddify / v2rayNG)

Returns the user's full proxy configuration as a base64-encoded subscription. This URL is what you import into Hiddify, v2rayNG, or sing-box-VT.

Response

Base64-encoded text body containing one or more
vless://, ss://, or hy2:// URIs (one per line).

cURL example

curl https://omnishield.io/sub/YOUR_SUB_TOKEN

Error codes

404 — Token not found or revoked