Security Baseline

Authentication Guide

ZentisLabs supports two authentication methods: API key (Bearer token) for REST API access and username:password for direct proxy connections. This guide covers both methods with code examples in cURL, Python, and Node.js.

Method 1: API Key Authentication

Use your API key as a Bearer token in the Authorization header for all REST API requests. You can generate API keys from the Dashboard.

cURL

bash

curl -X GET "https://api.zentislabs.com/api/v1/proxies" \
  -H "X-API-Key: YOUR_API_KEY"

Python (requests)

python

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.zentislabs.com/api"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
}

# List your proxies
response = requests.get(f"{BASE_URL}/v1/proxies", headers=headers)

if response.status_code == 200:
    data = response.json()["data"]
    print(f"Active proxies: {len(data)}")
else:
    print(f"Error {response.status_code}: {response.text}")

Node.js (axios)

typescript

import axios from "axios";

const API_KEY = process.env.ZENTISLABS_API_KEY!;
const client = axios.create({
  baseURL: "https://api.zentislabs.com/api",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
  },
  timeout: 10000,
});

// List proxies
const { data } = await client.get("/v1/proxies");
console.log("Active proxies:", data.data.length);

// Generate a proxy
const proxy = await client.post("/v1/proxy/generate", {
  type: "RESIDENTIAL",
  country: "DE",
  sessionType: "rotating",
});
console.log("Proxy:", proxy.data.data.proxy);

Method 2: Username:Password Proxy Auth

For direct proxy connections (HTTP/HTTPS/SOCKS5), authenticate using your proxy username and password. The format encodes targeting parameters directly in the username string.

Username Format

text

Format: customer-USERNAME-cc-COUNTRY-sessid-SESSION

Examples:
  customer-john_doe-cc-US                     → rotating US IP
  customer-john_doe-cc-DE-sessid-abc123       → sticky DE session
  customer-john_doe-cc-GB-city-london         → London, UK IP
  customer-john_doe-cc-JP-sesstype-residential → residential JP IP

cURL with Proxy Auth

bash

# Rotating residential proxy (US)
curl -x "http://customer-USERNAME-cc-US:PASSWORD@gate.zentislabs.com:8080" \
  "https://httpbin.org/ip"

# Sticky session (Germany, 10-minute session)
curl -x "http://customer-USERNAME-cc-DE-sessid-mysession1:PASSWORD@gate.zentislabs.com:8080" \
  "https://httpbin.org/ip"

# SOCKS5 connection
curl --socks5 "customer-USERNAME-cc-US:PASSWORD@gate.zentislabs.com:1080" \
  "https://httpbin.org/ip"

Python with Proxy Auth

python

import requests

USERNAME = "customer-john_doe-cc-US-sessid-scrape001"
PASSWORD = "YOUR_PROXY_PASSWORD"
PROXY_HOST = "gate.zentislabs.com"
PROXY_PORT = 8080

proxies = {
    "http": f"http://{USERNAME}:{PASSWORD}@{PROXY_HOST}:{PROXY_PORT}",
    "https": f"http://{USERNAME}:{PASSWORD}@{PROXY_HOST}:{PROXY_PORT}",
}

response = requests.get("https://httpbin.org/ip", proxies=proxies, timeout=30)
print("Your proxy IP:", response.json()["origin"])

# With session persistence for multi-request flows
session = requests.Session()
session.proxies = proxies

for i in range(5):
    r = session.get("https://httpbin.org/ip")
    print(f"Request {i+1}: {r.json()['origin']}")

Node.js with Proxy Auth

typescript

import axios from "axios";
import { HttpsProxyAgent } from "https-proxy-agent";

const proxyUrl = "http://customer-USERNAME-cc-US:PASSWORD@gate.zentislabs.com:8080";
const agent = new HttpsProxyAgent(proxyUrl);

const response = await axios.get("https://httpbin.org/ip", {
  httpsAgent: agent,
  timeout: 30000,
});

console.log("Proxy IP:", response.data.origin);

Error Handling

Common authentication errors and how to handle them:

401 Unauthorized

Invalid or expired API key. Check that you are passing the correct key and it has not been revoked.

json

{
  "error": "unauthorized",
  "message": "Invalid or expired API key",
  "code": 401
}

403 Forbidden

Key is valid but access was denied. Check that the key has not been revoked.

json

{
  "error": "forbidden",
  "message": "Access denied",
  "code": 403
}

429 Rate Limited

Too many requests. Implement exponential backoff and respect the Retry-After header.

python

import time
import requests

def make_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 2 ** attempt))
            print(f"Rate limited. Retrying in {retry_after}s...")
            time.sleep(retry_after)
            continue
        return response
    raise Exception("Max retries exceeded")

API Key Management

Store your API keys securely and never expose them in frontend code. Use environment variables or a secrets manager. Each key has a unique ID, type, and optional expiration date.

json

{
  "key_id": "key_prod_checkout",
  "type": "live",
  "prefix": "zlk_live_",
  "created_at": "2025-01-15T00:00:00Z",
  "expires_at": "2026-06-01T00:00:00Z"
}

Key Rotation Best Practices

Avoid

Sharing keys across environments (dev/staging/prod)
Committing keys to version control
Using a single key for all services
Keys without expiration or IP restrictions
Rotating immediately after personnel changes (no transition period)

Key Rotation Script

python

import requests
import os

API_KEY = os.environ["ZENTISLABS_API_KEY"]
BASE_URL = "https://api.zentislabs.com/api/v1"

# Step 1: Regenerate your API key (old key is revoked immediately)
new_key = requests.post(
    f"{BASE_URL}/user/regenerate-api-key",
    headers={"X-API-Key": API_KEY},
).json()

print(f"New key: {new_key['apiKey']}")

# Step 2: Update your secret manager / .env with the new key
# Step 3: Verify new key works by calling /api/v1/account
verify = requests.get(
    f"{BASE_URL}/account",
    headers={"X-API-Key": new_key['apiKey']},
)
print(f"Verified: {verify.json()['data']['email']}")

Security Checklist

API keys stored in environment variables or secret manager

IP allowlisting enabled for production keys

Separate keys per environment (dev / staging / prod)

Key rotation policy documented and automated

Failed auth monitoring and alerting configured

Unused keys regularly revoked

HTTPS enforced for all API and proxy connections

Audit logs reviewed monthly for anomalies

Next: Configure Proxy Pools

Apply auth best practices to real routing policies and geo-targeting.

Proxy Configuration

Security Baseline

Authentication Guide

Method 1: API Key Authentication

Use your API key as a Bearer token in the Authorization header for all REST API requests. You can generate API keys from the Dashboard.

cURL

bash

curl -X GET "https://api.zentislabs.com/api/v1/proxies" \
  -H "X-API-Key: YOUR_API_KEY"

Python (requests)

python

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.zentislabs.com/api"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
}

# List your proxies
response = requests.get(f"{BASE_URL}/v1/proxies", headers=headers)

if response.status_code == 200:
    data = response.json()["data"]
    print(f"Active proxies: {len(data)}")
else:
    print(f"Error {response.status_code}: {response.text}")

Node.js (axios)

typescript

import axios from "axios";

const API_KEY = process.env.ZENTISLABS_API_KEY!;
const client = axios.create({
  baseURL: "https://api.zentislabs.com/api",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
  },
  timeout: 10000,
});

// List proxies
const { data } = await client.get("/v1/proxies");
console.log("Active proxies:", data.data.length);

// Generate a proxy
const proxy = await client.post("/v1/proxy/generate", {
  type: "RESIDENTIAL",
  country: "DE",
  sessionType: "rotating",
});
console.log("Proxy:", proxy.data.data.proxy);

Method 2: Username:Password Proxy Auth

For direct proxy connections (HTTP/HTTPS/SOCKS5), authenticate using your proxy username and password. The format encodes targeting parameters directly in the username string.

Username Format

text

Format: customer-USERNAME-cc-COUNTRY-sessid-SESSION

Examples:
  customer-john_doe-cc-US                     → rotating US IP
  customer-john_doe-cc-DE-sessid-abc123       → sticky DE session
  customer-john_doe-cc-GB-city-london         → London, UK IP
  customer-john_doe-cc-JP-sesstype-residential → residential JP IP

cURL with Proxy Auth

bash

# Rotating residential proxy (US)
curl -x "http://customer-USERNAME-cc-US:PASSWORD@gate.zentislabs.com:8080" \
  "https://httpbin.org/ip"

# Sticky session (Germany, 10-minute session)
curl -x "http://customer-USERNAME-cc-DE-sessid-mysession1:PASSWORD@gate.zentislabs.com:8080" \
  "https://httpbin.org/ip"

# SOCKS5 connection
curl --socks5 "customer-USERNAME-cc-US:PASSWORD@gate.zentislabs.com:1080" \
  "https://httpbin.org/ip"

Python with Proxy Auth

python

import requests

USERNAME = "customer-john_doe-cc-US-sessid-scrape001"
PASSWORD = "YOUR_PROXY_PASSWORD"
PROXY_HOST = "gate.zentislabs.com"
PROXY_PORT = 8080

proxies = {
    "http": f"http://{USERNAME}:{PASSWORD}@{PROXY_HOST}:{PROXY_PORT}",
    "https": f"http://{USERNAME}:{PASSWORD}@{PROXY_HOST}:{PROXY_PORT}",
}

response = requests.get("https://httpbin.org/ip", proxies=proxies, timeout=30)
print("Your proxy IP:", response.json()["origin"])

# With session persistence for multi-request flows
session = requests.Session()
session.proxies = proxies

for i in range(5):
    r = session.get("https://httpbin.org/ip")
    print(f"Request {i+1}: {r.json()['origin']}")

Node.js with Proxy Auth

typescript

import axios from "axios";
import { HttpsProxyAgent } from "https-proxy-agent";

const proxyUrl = "http://customer-USERNAME-cc-US:PASSWORD@gate.zentislabs.com:8080";
const agent = new HttpsProxyAgent(proxyUrl);

const response = await axios.get("https://httpbin.org/ip", {
  httpsAgent: agent,
  timeout: 30000,
});

console.log("Proxy IP:", response.data.origin);

Error Handling

Common authentication errors and how to handle them:

401 Unauthorized

Invalid or expired API key. Check that you are passing the correct key and it has not been revoked.

json

{
  "error": "unauthorized",
  "message": "Invalid or expired API key",
  "code": 401
}

403 Forbidden

Key is valid but access was denied. Check that the key has not been revoked.

json

{
  "error": "forbidden",
  "message": "Access denied",
  "code": 403
}

429 Rate Limited

Too many requests. Implement exponential backoff and respect the Retry-After header.

python

import time
import requests

def make_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 2 ** attempt))
            print(f"Rate limited. Retrying in {retry_after}s...")
            time.sleep(retry_after)
            continue
        return response
    raise Exception("Max retries exceeded")

API Key Management

Store your API keys securely and never expose them in frontend code. Use environment variables or a secrets manager. Each key has a unique ID, type, and optional expiration date.

json

{
  "key_id": "key_prod_checkout",
  "type": "live",
  "prefix": "zlk_live_",
  "created_at": "2025-01-15T00:00:00Z",
  "expires_at": "2026-06-01T00:00:00Z"
}

Key Rotation Best Practices

Avoid

Sharing keys across environments (dev/staging/prod)
Committing keys to version control
Using a single key for all services
Keys without expiration or IP restrictions
Rotating immediately after personnel changes (no transition period)

Key Rotation Script

python

import requests
import os

API_KEY = os.environ["ZENTISLABS_API_KEY"]
BASE_URL = "https://api.zentislabs.com/api/v1"

# Step 1: Regenerate your API key (old key is revoked immediately)
new_key = requests.post(
    f"{BASE_URL}/user/regenerate-api-key",
    headers={"X-API-Key": API_KEY},
).json()

print(f"New key: {new_key['apiKey']}")

# Step 2: Update your secret manager / .env with the new key
# Step 3: Verify new key works by calling /api/v1/account
verify = requests.get(
    f"{BASE_URL}/account",
    headers={"X-API-Key": new_key['apiKey']},
)
print(f"Verified: {verify.json()['data']['email']}")

Security Checklist

API keys stored in environment variables or secret manager

IP allowlisting enabled for production keys

Separate keys per environment (dev / staging / prod)

Key rotation policy documented and automated

Failed auth monitoring and alerting configured

Unused keys regularly revoked

HTTPS enforced for all API and proxy connections

Audit logs reviewed monthly for anomalies

Next: Configure Proxy Pools

Apply auth best practices to real routing policies and geo-targeting.

Proxy Configuration

Authentication Guide

Method 1: API Key Authentication

cURL

Python (requests)

Node.js (axios)

Method 2: Username:Password Proxy Auth

Username Format

cURL with Proxy Auth

Python with Proxy Auth

Node.js with Proxy Auth

Error Handling

401 Unauthorized

403 Forbidden

429 Rate Limited

API Key Management

Key Rotation Best Practices

Recommended

Avoid

Key Rotation Script

Security Checklist

Next: Configure Proxy Pools

Authentication Guide

Method 1: API Key Authentication

cURL

Python (requests)

Node.js (axios)

Method 2: Username:Password Proxy Auth

Username Format

cURL with Proxy Auth

Python with Proxy Auth

Node.js with Proxy Auth

Error Handling

401 Unauthorized

403 Forbidden

429 Rate Limited

API Key Management

Key Rotation Best Practices

Recommended

Avoid

Key Rotation Script

Security Checklist

Next: Configure Proxy Pools