// Developer Reference

OmniShield API Documentation

Public REST API for the OmniShield VPN platform. Build clients, integrations, and automation against our endpoints. Base URL: https://api.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://api.omnishield.io/sub/abc123..."
}

cURL example

curl -X POST https://api.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://api.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://api.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://api.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://api.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": "shadowsocks", "name": "Shadowsocks 2022", "port": 2054, "censorship_resistant": true },
  { "id": "awg", "name": "AmneziaWG", "port": 51820, "censorship_resistant": true }
]

cURL example

curl https://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.omnishield.io/api/referral/code \
  -H "Authorization: Bearer YOUR_JWT"

# System & Subscription

GET/api/healthpublic

Health check

Liveness probe. Returns 200 when the API is healthy.

Response

{ "status": "ok" }

cURL example

curl https://api.omnishield.io/api/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 FoXray.

Response

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

cURL example

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

Error codes

404 — Token not found or revoked