ZEO API Documentation
Secure Tunneling — API Reference
Complete reference for the ZEO platform REST API. Authenticate, manage tunnels, handle payments, administer users, and inspect traffic — all through a consistent JSON API.
🚀
Try it with cURL
All API endpoints accept and return JSON. Start by registering a user, then use the returned JWT token in the Authorization header for subsequent requests.
Step 1 — Register a new account
# Register and receive a JWT token
curl -X POST https://platform.ohwhere.io/api/register \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]","password":"your-password","username":"johndoe"}'
Step 2 — Fetch your stats
# Use your JWT token
curl -X GET https://platform.ohwhere.io/api/stats \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Step 3 — Checkout a Pro plan
# Returns a Stripe checkout URL
curl -X POST https://platform.ohwhere.io/api/checkout \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"packageId":"pkg_pro"}'
🔐
Authentication
POST/api/login
Authenticate an existing user and receive a JWT token.
Request Body
{
"email": "[email protected]",
"password": "your-password"
}
Response — 200 OK
{
"jwtToken": "eyJhbGciOiJIUzI1NiIs...",
"token": "eyJhbGciOiJIUzI1NiIs...",
"user": {
"id": "clx...",
"email": "[email protected]",
"username": "johndoe",
"plan": "pro",
"maxPorts": 10,
"subdomain": "johndoe"
}
}
cURL Example
curl -X POST https://platform.ohwhere.io/api/login \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"password": "your-password"
}'
POST/api/register
Create a new user account.
Request Body
{
"email": "[email protected]",
"password": "your-password",
"username": "johndoe"
}
Response — 200 OK
{
"jwtToken": "eyJhbGciOiJIUzI1NiIs...",
"token": "eyJhbGciOiJIUzI1NiIs...",
"user": {
"id": "clx...",
"email": "[email protected]",
"username": "johndoe",
"plan": "free",
"maxPorts": 1,
"subdomain": "johndoe"
}
}
cURL Example
curl -X POST https://platform.ohwhere.io/api/register \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"password": "your-password",
"username": "johndoe"
}'
📊
User Dashboard
GET/api/statsRequires JWT
Retrieve the authenticated user's tunnel statistics.
Headers
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json
Response — 200 OK
{
"tunnels": 3,
"bandwidth": "12.4 GB",
"requests": 84251
}
cURL Example
curl -X GET https://platform.ohwhere.io/api/stats \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
POST/api/usageRequires JWT
Report bandwidth and connection usage for the authenticated user.
Headers
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json
Request Body
{
"bytesIn": 1048576,
"bytesOut": 2097152,
"requests": 420,
"connections": 12
}
cURL Example
curl -X POST https://platform.ohwhere.io/api/usage \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-d '{
"bytesIn": 1048576,
"bytesOut": 2097152,
"requests": 420,
"connections": 12
}'
📦
Packages
GET/api/packages
List all available subscription packages.
Response — 200 OK
{
"packages": [
{
"id": "pkg_free",
"name": "free",
"displayName": "Free",
"price": 0,
"maxPorts": 1,
"description": "Perfect for trying out ZEO",
"features": ["1 tunnel", "Basic support"],
"isActive": true
},
{
"id": "pkg_pro",
"name": "pro",
"displayName": "Pro",
"price": 9.99,
"maxPorts": 10,
"description": "For developers who need more power",
"features": ["10 tunnels", "Custom subdomain", "Priority support"],
"isActive": true
}
]
}
cURL Example
curl -X GET https://platform.ohwhere.io/api/packages \
-H "Content-Type: application/json"
POST/api/packagesRequires JWT
Create a new subscription package (admin only).
Headers
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json
Request Body
{
"name": "enterprise",
"displayName": "Enterprise",
"price": 49.99,
"maxPorts": 50,
"description": "For large teams and organizations",
"features": ["50 tunnels", "Custom domain", "SLA", "Dedicated support"],
"isActive": true,
"sortOrder": 3
}
cURL Example
curl -X POST https://platform.ohwhere.io/api/packages \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-d '{
"name": "enterprise",
"displayName": "Enterprise",
"price": 49.99,
"maxPorts": 50,
"description": "For large teams and organizations",
"features": ["50 tunnels", "Custom domain", "SLA", "Dedicated support"],
"isActive": true,
"sortOrder": 3
}'
💳
Payments
POST/api/checkoutRequires JWT
Initiate a Stripe Checkout session for a subscription package.
Headers
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json
Request Body
{
"packageId": "pkg_pro"
}
Response — 200 OK
{
"url": "https://checkout.stripe.com/c/pay/cs_live_..."
}
cURL Example
curl -X POST https://platform.ohwhere.io/api/checkout \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-d '{
"packageId": "pkg_pro"
}'
POST/api/stripe-webhook
Webhook endpoint for Stripe events. Called automatically by Stripe when payment events occur (checkout.session.completed, customer.subscription.deleted, etc.).
cURL Example
curl -X POST https://platform.ohwhere.io/api/stripe-webhook \
-H "Content-Type: application/json"
Note: This endpoint is called by Stripe — do not call it directly.
🛡️
Admin
POST/api/admin/auth
Authenticate as an administrator.
Request Body
{
"password": "admin-secret-password"
}
Response — 200 OK
{
"success": true,
"token": "eyJhbGciOiJIUzI1NiIs..."
}
cURL Example
curl -X POST https://platform.ohwhere.io/api/admin/auth \
-H "Content-Type: application/json" \
-d '{
"password": "admin-secret-password"
}'
GET/api/admin/statsRequires Admin Token
Retrieve global platform statistics.
Headers
Authorization: Bearer YOUR_ADMIN_TOKEN
Content-Type: application/json
Response — 200 OK
{
"totalUsers": 1248,
"activeSubscriptions": 384,
"totalRevenue": 4215.60,
"recentUsers": [
{ "id": "clx...", "email": "[email protected]", "plan": "free", "createdAt": "2024-12-01" }
],
"recentPayments": [
{ "id": "pay_...", "amount": 9.99, "userEmail": "[email protected]", "createdAt": "2024-12-01" }
],
"usersByPlan": { "free": 864, "pro": 320, "enterprise": 64 }
}
cURL Example
curl -X GET https://platform.ohwhere.io/api/admin/stats \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN"
GET/api/admin/usersRequires Admin Token
List all registered users.
Headers
Authorization: Bearer YOUR_ADMIN_TOKEN
Content-Type: application/json
Response — 200 OK
{
"users": [
{
"id": "clx...",
"email": "[email protected]",
"username": "johndoe",
"plan": "pro",
"maxPorts": 10,
"subdomain": "johndoe",
"createdAt": "2024-11-15"
}
]
}
cURL Example
curl -X GET https://platform.ohwhere.io/api/admin/users \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN"
PATCH/api/admin/usersRequires Admin Token
Update a user's plan, port limit, or subdomain.
Headers
Authorization: Bearer YOUR_ADMIN_TOKEN
Content-Type: application/json
Request Body
{
"id": "clx...",
"plan": "pro",
"maxPorts": 10,
"subdomain": "custom-name"
}
cURL Example
curl -X PATCH https://platform.ohwhere.io/api/admin/users \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
-d '{
"id": "clx...",
"plan": "pro",
"maxPorts": 10,
"subdomain": "custom-name"
}'
DELETE/api/admin/users/[id]Requires Admin Token
Delete a user account by ID.
Headers
Authorization: Bearer YOUR_ADMIN_TOKEN
Content-Type: application/json
cURL Example
curl -X DELETE https://platform.ohwhere.io/api/admin/users/[id] \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN"
GET/api/admin/content
Retrieve the configurable landing-page content (hero, features, plans).
Response — 200 OK
{
"hero": { "badge": "...", "title": "...", "subtitle": "..." },
"features": [ { "title": "...", "description": "...", "icon": "..." } ],
"plans": [ { "name": "...", "price": 0, "features": ["..."] } ]
}
cURL Example
curl -X GET https://platform.ohwhere.io/api/admin/content \
-H "Content-Type: application/json"
PUT/api/admin/contentRequires Admin Token
Update landing-page content sections.
Headers
Authorization: Bearer YOUR_ADMIN_TOKEN
Content-Type: application/json
Request Body
{
"hero": {
"badge": "New Feature",
"title": "ZEO — Secure Tunneling",
"subtitle": "Expose local services securely."
},
"features": [
{ "title": "Encrypted Tunnels", "description": "...", "icon": "shield" }
],
"plans": [
{ "name": "Pro", "price": 9.99, "features": ["10 tunnels"] }
]
}
cURL Example
curl -X PUT https://platform.ohwhere.io/api/admin/content \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
-d '{
"hero": {
"badge": "New Feature",
"title": "ZEO — Secure Tunneling",
"subtitle": "Expose local services securely."
},
"features": [
{ "title": "Encrypted Tunnels", "description": "...", "icon": "shield" }
],
"plans": [
{ "name": "Pro", "price": 9.99, "features": ["10 tunnels"] }
]
}'
GET/api/admin/downloadsRequires Admin Token
List all downloadable client releases.
Headers
Authorization: Bearer YOUR_ADMIN_TOKEN
Content-Type: application/json
cURL Example
curl -X GET https://platform.ohwhere.io/api/admin/downloads \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN"
POST/api/admin/downloadsRequires Admin Token
Upload a new client release for download.
Headers
Authorization: Bearer YOUR_ADMIN_TOKEN
Content-Type: application/json
Request Body
{
"fileName": "zeo-client-v2.1.0-macos.zip",
"platform": "macos",
"version": "2.1.0",
"size": "24 MB",
"releaseNotes": "Added multi-port support and improved stability."
}
cURL Example
curl -X POST https://platform.ohwhere.io/api/admin/downloads \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
-d '{
"fileName": "zeo-client-v2.1.0-macos.zip",
"platform": "macos",
"version": "2.1.0",
"size": "24 MB",
"releaseNotes": "Added multi-port support and improved stability."
}'
DELETE/api/admin/downloads/[id]Requires Admin Token
Remove a download release by ID.
Headers
Authorization: Bearer YOUR_ADMIN_TOKEN
Content-Type: application/json
cURL Example
curl -X DELETE https://platform.ohwhere.io/api/admin/downloads/[id] \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN"
GET/api/admin/settingsRequires Admin Token
Retrieve platform configuration settings.
Headers
Authorization: Bearer YOUR_ADMIN_TOKEN
Content-Type: application/json
cURL Example
curl -X GET https://platform.ohwhere.io/api/admin/settings \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN"
PATCH/api/admin/settingsRequires Admin Token
Update platform configuration settings.
Headers
Authorization: Bearer YOUR_ADMIN_TOKEN
Content-Type: application/json
Request Body
{
"baseDomain": "ohwhere.io",
"platformUrl": "https://platform.ohwhere.io",
"smtpHost": "smtp.example.com",
"smtpPort": 587,
"smtpUser": "[email protected]",
"smtpPass": "smtp-password",
"maintenanceMode": false
}
cURL Example
curl -X PATCH https://platform.ohwhere.io/api/admin/settings \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
-d '{
"baseDomain": "ohwhere.io",
"platformUrl": "https://platform.ohwhere.io",
"smtpHost": "smtp.example.com",
"smtpPort": 587,
"smtpUser": "[email protected]",
"smtpPass": "smtp-password",
"maintenanceMode": false
}'
🔍
Traffic Inspector
GET/api/admin/traffic?page=1&limit=50&method=&protocol=&search=Requires Admin Token
List traffic log entries with optional filtering and pagination.
Headers
Authorization: Bearer YOUR_ADMIN_TOKEN
Content-Type: application/json
Response — 200 OK
{
"data": [
{
"id": "log_...",
"userId": "clx...",
"subdomain": "johndoe",
"method": "GET",
"path": "/api/data",
"statusCode": 200,
"userAgent": "Mozilla/5.0 ...",
"sourceIp": "203.0.113.42",
"bytesIn": 256,
"bytesOut": 4096,
"responseTime": 45,
"protocol": "HTTPS",
"createdAt": "2024-12-01T12:34:56Z"
}
],
"total": 1520,
"page": 1,
"limit": 50
}
cURL Example
curl -X GET https://platform.ohwhere.io/api/admin/traffic \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN"
GET/api/admin/traffic/statsRequires Admin Token
Retrieve aggregate traffic statistics.
Headers
Authorization: Bearer YOUR_ADMIN_TOKEN
Content-Type: application/json
Response — 200 OK
{
"totalRequests": 128420,
"totalBytesIn": 2147483648,
"totalBytesOut": 8589934592,
"avgResponseTime": 32.5,
"byMethod": { "GET": 82400, "POST": 38200, "PUT": 4100, "DELETE": 3720 },
"byProtocol": { "HTTPS": 120000, "HTTP": 8420 },
"topSubdomains": [
{ "subdomain": "api", "hits": 42000 },
{ "subdomain": "web", "hits": 31000 }
]
}
cURL Example
curl -X GET https://platform.ohwhere.io/api/admin/traffic/stats \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN"
GET/api/admin/traffic/export?method=&protocol=&search=Requires Admin Token
Export traffic logs as a downloadable CSV file with optional filters.
Headers
Authorization: Bearer YOUR_ADMIN_TOKEN
Content-Type: application/json
cURL Example
curl -X GET https://platform.ohwhere.io/api/admin/traffic/export \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN"
Note: Returns a CSV file download.
POST/api/traffic/log
Log a single traffic entry (called by the tunnel relay).
Request Body
{
"userId": "clx...",
"subdomain": "johndoe",
"method": "GET",
"path": "/api/data",
"statusCode": 200,
"userAgent": "Mozilla/5.0 ...",
"sourceIp": "203.0.113.42",
"bytesIn": 256,
"bytesOut": 4096,
"responseTime": 45,
"protocol": "HTTPS"
}
cURL Example
curl -X POST https://platform.ohwhere.io/api/traffic/log \
-H "Content-Type: application/json" \
-d '{
"userId": "clx...",
"subdomain": "johndoe",
"method": "GET",
"path": "/api/data",
"statusCode": 200,
"userAgent": "Mozilla/5.0 ...",
"sourceIp": "203.0.113.42",
"bytesIn": 256,
"bytesOut": 4096,
"responseTime": 45,
"protocol": "HTTPS"
}'
🌱
Seed
GET/api/seed
Seed the database with default subscription packages. Useful for initial setup or resetting package data.
Response — 200 OK
{
"message": "Packages seeded successfully"
}
cURL Example
curl -X GET https://platform.ohwhere.io/api/seed \
-H "Content-Type: application/json"
Note: Should only be called during initial deployment or development.