VPN Session Lifecycle

VPN sessions track connection time and manage credit consumption. The session lifecycle consists of four operations: start, heartbeat, end, and active check. Proper session management ensures accurate credit tracking and clean disconnections.

Start Session

Initialize a new VPN session. Call this immediately after establishing a VPN connection to begin credit tracking.

POST/api/v1/vpn/session/start

Start a new VPN session

Authentication:Bearer Token

Parameter	Type	Required	Description
`session_id`	string	Required	A unique session identifier generated by the client (UUID recommended)
`server_id`	integer	Required	The ID of the server the user is connected to
`protocol`	string	Required	VPN protocol in use: wireguard, vless, or orbconnect

curl -X POST https://api.orbai.world/api/v1/vpn/session/start \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "server_id": 101,
    "protocol": "wireguard"
  }'

200Session started successfully

{
  "success": true,
  "data": {
    "session_id": "sess_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tracking_id": "trk_98765432",
    "is_free_user": false,
    "credits_at_start": 5000,
    "consumption_rate": 1.5,
    "next_deduction_in_seconds": 60
  }
}

409Session already active

{
  "success": false,
  "error": {
    "code": "SESSION_ALREADY_ACTIVE",
    "message": "An active VPN session already exists. End the current session before starting a new one."
  }
}

Session Heartbeat

Send periodic heartbeats to keep the session alive and update credit consumption. Heartbeats should be sent at regular intervals (recommended: every 30-120 seconds).

POST/api/v1/vpn/session/heartbeat

Send a session heartbeat with usage data

Authentication:Bearer Token

Parameter	Type	Required	Description
`session_id`	string	Required	The active session ID
`seconds_since_last`	integer	Required	Seconds elapsed since the last heartbeat or session start (1-300)

Heartbeat Interval

The seconds_since_last value must be between 1 and 300 (5 minutes). If no heartbeat is received within 5 minutes, the session may be automatically terminated by the server.

curl -X POST https://api.orbai.world/api/v1/vpn/session/heartbeat \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "seconds_since_last": 60
  }'

200Heartbeat processed successfully

{
  "success": true,
  "data": {
    "session_id": "sess_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "credits_remaining": 4910,
    "credits_deducted": 1.5,
    "consumption_rate": 1.5,
    "next_deduction_in_seconds": 60,
    "session_duration_secs": 120
  }
}

402Credits depleted

{
  "success": false,
  "error": {
    "code": "CREDITS_DEPLETED",
    "message": "Your credits have been depleted. The session will be terminated."
  }
}

End Session

Gracefully end the active VPN session. Call this when the user disconnects. The response includes a summary of the completed session.

POST/api/v1/vpn/session/end

End an active VPN session

Authentication:Bearer Token

Parameter	Type	Required	Description
`session_id`	string	Required	The active session ID to terminate
`seconds_since_last`	integer	Required	Seconds elapsed since the last heartbeat (1-300)
`disconnect_reason`	string	Required	Reason for disconnection: user_initiated, credits_depleted, error, or timeout

curl -X POST https://api.orbai.world/api/v1/vpn/session/end \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "seconds_since_last": 45,
    "disconnect_reason": "user_initiated"
  }'

200Session ended successfully with summary

{
  "success": true,
  "data": {
    "session_id": "sess_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "total_duration_secs": 3600,
    "total_credits_used": 90.0,
    "credits_remaining": 4910,
    "disconnect_reason": "user_initiated",
    "ended_at": "2026-02-08T10:30:00Z"
  }
}

404Session not found

{
  "success": false,
  "error": {
    "code": "SESSION_NOT_FOUND",
    "message": "No active session found with the specified ID"
  }
}

Check Active Session

Check whether the authenticated user has an active VPN session.

GET/api/v1/vpn/session/active

Check for an active VPN session

Authentication:Bearer Token

curl -X GET https://api.orbai.world/api/v1/vpn/session/active \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

200Active session found

{
  "success": true,
  "data": {
    "has_active_session": true,
    "session": {
      "session_id": "sess_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "server_id": 101,
      "protocol": "wireguard",
      "started_at": "2026-02-08T09:30:00Z",
      "duration_secs": 3600,
      "credits_remaining": 4910
    }
  }
}

200No active session

{
  "success": true,
  "data": {
    "has_active_session": false,
    "session": null
  }
}

Disconnect Reasons

When ending a session, use the appropriate disconnect reason:

user_initiated -- The user manually disconnected.
credits_depleted -- The session ended because credits ran out.
error -- The connection was lost due to a network or client error.
timeout -- The session timed out due to inactivity (no heartbeats received).

Heartbeat Best Practices

Send heartbeats every 30-60 seconds for accurate credit tracking. If a heartbeat fails due to a network issue, retry with exponential backoff. Always attempt to send an end-session request when disconnecting, even if previous heartbeats failed.

VPN Sessions

VPN Session Lifecycle

Start Session

Session Heartbeat

Heartbeat Interval

End Session

Check Active Session

Disconnect Reasons

Heartbeat Best Practices

On this page