API Reference

Generate a device-level API key and give it to your customer. They can create, manage, and delete proxy ports on that device — nothing else.

API Keys

Create API keys to authenticate without sharing your login credentials. Keys never expire unless you delete them.

Loading...

How It Works

Create an API key, manage all your devices and proxy ports.

1.

Create an API key

Dashboard keys have full access. Device keys are locked to one device.

2.

Use short IDs

All endpoints accept the 8-character short ID shown on the dashboard (e.g. d5414586).

3.

Manage ports & devices

Create HTTP/SOCKS5 ports, rotate IPs, check bandwidth — all via API.

Authentication

# List your devices
curl https://pocketproxy.io/api/v1/devices \
  -H "Authorization: Bearer pp_live_your_key_here"

# Get connections on a device (includes proxy_host for connecting)
curl https://pocketproxy.io/api/v1/devices/d5414586/connections \
  -H "Authorization: Bearer pp_live_your_key_here"

All endpoints use Authorization: Bearer pp_live_... — that's it. Device keys scope access to one device. Dashboard keys give full account access.

Base URL: https://pocketproxy.io/api/v1 · Rate limit: 500 req/min per client IP (not per key — keys called from the same server share one budget) · Auth: Bearer pp_live_...

Short IDs: All endpoints accept 8-character ID prefixes (e.g. d5414586) instead of full UUIDs. Use the short device ID from the dashboard to list all connections on a device.

Admin keys: Keys created by admin users have full platform access — they can see all devices and connections across all customers.

Endpoints

Everything a device API key can do. Credentials are auto-generated — just pick http or socks5.

Devices

Connections

Two rules that surprise most integrations.

1. New connections start inactive. A connection created on a customer-owned device comes back with active: false and carries no traffic until the device has a paid plan. Buy one with POST /v1/billing/purchase, or activate an already-paid connection with PATCH /v1/connections/:id. Activating with no plan returns 402, not a server error.

2. Each device has an access-point cap. The plan decides how many connections a device may hold — read max_access_points from GET /v1/billing/tiers. A device with no plan is capped at 3. Creating one past the cap returns 409. Existing connections are never deleted when a plan is downgraded; only new ones are blocked.

What expires_at and auto_renew mean. expires_at is the end of the current paid billing period, not a date the proxy shuts off. With auto_renew: true the account is charged when that moment arrives (balance first, then the card on file) and expires_at moves forward by one full period from the old date, so no days are lost and the port keeps serving traffic throughout. Read the new value from GET /v1/devices/:id/connections at any time.

The port only stops when the charge fails. That's the case the connection.expired webhook reports, and the connection comes back with active: false. If you resell access, don't treat expires_at as a hard deadline while auto_renew is true. Treat the webhook, or an active: false read, as the signal that service ended.

Connection Actions

Using the Proxy

Get the proxy host from GET /v1/devices/:id/connections (the proxy_host field) and the credentials from the connection object. Use them with any HTTP/SOCKS5 client.

HTTP Proxy (curl)

curl -x http://USERNAME:PASSWORD@PROXY_HOST:HTTP_PORT https://httpbin.org/ip

SOCKS5 Proxy (curl)

curl --socks5 USERNAME:PASSWORD@PROXY_HOST:SOCKS5_PORT https://httpbin.org/ip

Python

import requests

proxies = {
    "http": "http://USERNAME:PASSWORD@PROXY_HOST:HTTP_PORT",
    "https": "http://USERNAME:PASSWORD@PROXY_HOST:HTTP_PORT",
}
response = requests.get("https://httpbin.org/ip", proxies=proxies)
print(response.json())

Node.js

const { HttpsProxyAgent } = require('https-proxy-agent');
const axios = require('axios');

const agent = new HttpsProxyAgent('http://USERNAME:PASSWORD@PROXY_HOST:HTTP_PORT');
const res = await axios.get('https://httpbin.org/ip', { httpsAgent: agent });
console.log(res.data);

Full Integration Examples

End-to-end: create a port, use it, delete it.

Python

import requests

API_KEY = "pp_live_YOUR_DEVICE_KEY"
BASE = "https://pocketproxy.io/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# List devices — get telemetry (battery, carrier, IP, etc.)
devices = requests.get(f"{BASE}/devices", headers=HEADERS).json()["devices"]
device = devices[0]
print(f"Device: {device['name']} | {device['carrier']} | Battery: {device['battery_level']}%")

# Get connections on the device (includes proxy_host)
conns = requests.get(f"{BASE}/devices/{device['id']}/connections", headers=HEADERS).json()["connections"]
conn = conns[0]
proxy_host = conn["proxy_host"]

# Use the proxy
proxies = {"http": f"http://{conn['username']}:{conn['password']}@{proxy_host}:{conn['http_port']}",
           "https": f"http://{conn['username']}:{conn['password']}@{proxy_host}:{conn['http_port']}"}
ip = requests.get("https://httpbin.org/ip", proxies=proxies).json()
print(f"Proxy IP: {ip['origin']}")

# Create a new connection
new = requests.post(f"{BASE}/connections", headers=HEADERS, json={
    "proxy_type": "http", "name": "Customer Port 1"
}).json()
print(f"Created: {new['username']}:{new['password']} @ port {new['http_port']}")

# Delete when done
requests.delete(f"{BASE}/connections/{new['id']}", headers=HEADERS)

JavaScript (Node.js)

const { HttpsProxyAgent } = require('https-proxy-agent');
const axios = require('axios');

const API_KEY = "pp_live_YOUR_DEVICE_KEY";
const BASE = "https://pocketproxy.io/api/v1";
const headers = { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" };

// List devices with telemetry
const { data: { devices } } = await axios.get(`${BASE}/devices`, { headers });
const device = devices[0];
console.log(`Device: ${device.name} | ${device.carrier} | Battery: ${device.battery_level}%`);

// Get connections on device (includes proxy_host)
const { data: { connections } } = await axios.get(`${BASE}/devices/${device.id}/connections`, { headers });
const conn = connections[0];
console.log(`Proxy: ${conn.username}@${conn.proxy_host}:${conn.http_port}`);

// Create a new connection
const { data: newConn } = await axios.post(`${BASE}/connections`, {
  proxy_type: "http", name: "Customer Port 1"
}, { headers });
console.log(`Created: ${newConn.username}:${newConn.password} @ port ${newConn.http_port}`);

// Delete when done
await axios.delete(`${BASE}/connections/${newConn.id}`, { headers });

PHP

<?php
$apiKey = "pp_live_YOUR_DEVICE_KEY";
$base = "https://pocketproxy.io/api/v1";

function api($method, $path, $body = null) {
    global $apiKey, $base;
    $ch = curl_init("$base$path");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer $apiKey",
        "Content-Type: application/json"
    ]);
    if ($method !== "GET") {
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
        if ($body) curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
    }
    return json_decode(curl_exec($ch), true);
}

// List devices with telemetry
$devices = api("GET", "/devices")["devices"];
$device = $devices[0];
echo "Device: {$device['name']} | {$device['carrier']} | Battery: {$device['battery_level']}%\n";

// Get connections on device (includes proxy_host)
$conns = api("GET", "/devices/{$device['id']}/connections")["connections"];
foreach ($conns as $c) {
    echo "  {$c['proxy_host']}:{$c['http_port']} — {$c['username']}\n";
}

// Create connection
$conn = api("POST", "/connections", ["proxy_type" => "http", "name" => "Port 1"]);
echo "Created: {$conn['username']}:{$conn['password']} @ port {$conn['http_port']}\n";

// Delete
api("DELETE", "/connections/{$conn['id']}");

Billing (Dashboard Keys Only)

API Keys (Dashboard Keys Only)

Webhooks (Dashboard Keys Only)

Receive HMAC-SHA256 signed callbacks for real-time events. Requires a dashboard-scoped API key.

device.offlineDevice goes offline
connection.expiredPlan lapsed and wasn't renewed
connection.ip_rotatedIP address changes
connection.bandwidth_warning80% bandwidth used

Verify the X-PocketProxy-Signature header:

import hmac, hashlib

def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)
Base URL: https://pocketproxy.io/api/v1 · All responses are JSON · UTC timestamps