REST + gRPC + WebSocket

OrbVPN Developer Platform

Build powerful integrations with three production-grade API services. Manage VPN connectivity, mesh networks, and advanced security intelligence through REST, gRPC, and WebSocket protocols.

Authentication Guide

REST Endpoints

gRPC RPCs

API Uptime

Response Time

Three Services, One Platform

OrbVPN's API platform is organized into three specialized services, each powering a different aspect of the platform.

OrbNET API

Core VPN platform backend. Authentication, user management, subscriptions, VPN connectivity, Smart DNS, token economy, and more.

OrbMesh Server API

VPN server protocol layer. WireGuard, VLESS, OrbConnect tunnels, Smart DNS, protocol mimicry, bridge mode, and health monitoring.

OrbGuard Labs API

Threat intelligence and device security. Spyware forensics, scam detection, dark web monitoring, YARA rules, network audit, and enterprise features.

Base URLs

Service	Base URL	Protocol
OrbNET REST	`https://api.orbai.world`	HTTPS
OrbNET gRPC	`grpc://api.orbai.world:50051`	gRPC + TLS
OrbNET WebSocket	`wss://api.orbai.world/ws`	WSS
OrbMesh Server	Per-server IP (port 8443)	HTTPS
OrbGuard Labs	`https://guard.orbai.world`	HTTPS

Quick Start

Get up and running in under 5 minutes.

Get Your Credentials

Create an OrbVPN account or request API access from the dashboard. You'll receive credentials for JWT authentication.

Authenticate

Call the login endpoint to receive JWT access and refresh tokens for making authenticated requests.

Make Your First Request

Use your access token to call any protected endpoint. Start with fetching your user profile or listing available VPN servers.

Explore the APIs

Dive into the three service APIs to build VPN integrations, mesh network management, or security intelligence features.

Authentication

All protected endpoints require a JWT Bearer token in the Authorization header.

POST/api/v1/auth/login

Authenticate and receive JWT tokens

curl -X POST https://api.orbai.world/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your_password"
  }'

200Successful authentication

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2...",
    "expiresAt": "2026-02-08T12:00:00Z",
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "role": "user"
    }
  }
}

Then include the token in subsequent requests:

curl https://api.orbai.world/api/v1/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Token Lifecycle

Access tokens expire after 24 hours. Use the refresh token endpoint (POST /api/v1/auth/refresh) to obtain new tokens without re-authenticating. See the full Authentication Guide for details on OAuth, passkeys, magic links, and 2FA.

Protocol Support

OrbVPN supports three communication protocols. Choose the right one for your use case.

REST API

Standard HTTP/HTTPS with JSON payloads. Best for web and mobile app integrations, CRUD operations, and general-purpose API calls.

gRPC

High-performance RPC with Protocol Buffers. Used for server-to-server communication, real-time streaming, and low-latency operations.

WebSocket

Persistent bidirectional connections for real-time updates. Used for notifications, live chat, threat alerts, and connection monitoring.

Error Handling

All API responses follow a consistent format:

Success Response

Contains "success": true and a "data" field with the requested information.

Error Response

Contains "success": false and an "error" object with code and message fields.

400Error response format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email address is required",
    "details": {
      "field": "email",
      "constraint": "required"
    }
  }
}

See the full Error Reference for all error codes.

Rate Limiting

API requests are rate-limited to ensure fair usage. Limits vary by endpoint and authentication tier.

Tier	Limit	Scope
Global	100 req/min	Per IP address
Auth endpoints	10 req/min	Per IP (login, register)
Protected endpoints	300 req/min	Per authenticated user
Admin endpoints	1000 req/min	Per admin user

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1707350400

See the full Rate Limiting Guide for retry strategies and best practices.

Explore the API

POSTLogin

Authenticate users and get access tokens

POSTRegister

Create new user accounts

GETGet User Profile

Retrieve authenticated user's profile

GETList VPN Servers

Get available VPN server locations

POSTCheck Threat Indicator

Check if a domain, IP, or hash is malicious

POSTAnalyze for Scams

AI-powered scam detection for text, URLs, and images

Development Tools

Postman

Import our API collections for interactive testing with pre-configured environments.

gRPCurl

Command-line tool for interacting with gRPC services. Perfect for testing streaming RPCs.

WebSocket Tester

Test WebSocket connections and event subscriptions in real-time.

Legacy GraphQL API Deprecated

The Legacy GraphQL API documented under "Legacy GraphQL (Deprecated)" is deprecated and will be removed in a future release. All new integrations should use the REST, gRPC, or WebSocket APIs documented above. Existing clients should migrate at their earliest convenience.

Need Help?

Our developer support team is available 24/7. Check out the Authentication Guide, explore the API reference for OrbNET, OrbMesh, or OrbGuard Labs, or reach out through the support portal.

Ready to Build?

Start building powerful integrations with OrbVPN's three-service API platform. Over 460 REST endpoints, 870 gRPC RPCs, and real-time WebSocket streams.

View OrbNET API

Getting Started with OrbVPN APIs