Authorize VPN Connection

Before establishing a VPN connection, your client must call this endpoint to verify that the user is authorized to connect. The server checks subscription status, available credits, device eligibility, and server availability.

POST/api/v1/vpn/authorize

Authorize a VPN connection and validate user eligibility

Authentication:Bearer Token

Parameter	Type	Required	Description
`server_id`	integer	Optional	ID of the specific server to connect to. If omitted, the system may auto-select an optimal server.
`protocol`	string	Required	VPN protocol to use: wireguard, vless, or orbconnect

Authorization Flow

The typical VPN connection flow is:

Authorize -- Call this endpoint to verify eligibility and reserve a connection slot.
Get Config -- Fetch the WireGuard or VLESS configuration for the authorized server.
Start Session -- Begin the VPN session to start credit tracking.
Heartbeat -- Send periodic heartbeats to maintain the session.
End Session -- Gracefully terminate the session when disconnecting.

# POST method
curl -X POST https://api.orbai.world/api/v1/vpn/authorize \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": 101,
    "protocol": "wireguard"
  }'

# GET method (alternative)
curl -X GET "https://api.orbai.world/api/v1/vpn/authorize?protocol=wireguard&server_id=101" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

200VPN connection authorized successfully

{
  "success": true,
  "data": {
    "authorized": true,
    "server_id": 101,
    "protocol": "wireguard",
    "credits": {
      "available": 5000,
      "consumption_rate": 1.5,
      "estimated_hours": 55.5
    }
  }
}

403User not authorized to connect

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "You do not have enough credits for a VPN connection. Please top up your balance or upgrade your subscription."
  }
}

403Subscription expired

{
  "success": false,
  "error": {
    "code": "SUBSCRIPTION_EXPIRED",
    "message": "Your subscription has expired. Please renew to continue using VPN services."
  }
}

400Invalid protocol specified

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid protocol. Must be one of: wireguard, vless, orbconnect"
  }
}

Authorize via GET

The authorization endpoint also supports GET requests with query parameters. This is useful for simple pre-flight checks.

GET/api/v1/vpn/authorize

Authorize a VPN connection via query parameters

Authentication:Bearer Token

Parameter	Type	Required	Description
`protocol`	string	Required	VPN protocol to use: wireguard, vless, or orbconnect
`server_id`	integer	Optional	ID of the target server

Protocol Selection

wireguard -- Fastest protocol with excellent performance. Best for general use.
vless -- XTLS-based protocol with superior obfuscation. Best for restrictive networks.
orbconnect -- OrbVPN's proprietary protocol combining speed and stealth. Adaptive and recommended for most users.

VPN Authorization

Authorize VPN Connection

Authorization Flow

Authorize via GET

Protocol Selection

On this page