Managing X4B Services via the Public API (APIv2)

The X4B APIv2 provides programmatic access to manage your X4B services, DNS records, firewall rules, SSL certificates, tunnels, and more. It is a REST-style API with JSON responses by default, available at the following base URL:

https://www.x4b.net/apiv2/{Module}/{Method}

Requests accept URL query parameters and POST bodies encoded as application/json, application/x-www-form-urlencoded or multipart/form-data. The legacy text/json content type is also accepted; use application/json for new integrations. JSON bodies use nested objects, while query and form parameters use bracketed names such as query[id] and value[ttl].

When a parameter appears in both the URL and body, the body takes precedence at the top level: a body query object replaces the URL's whole query object. Put each parameter group in one location.

Successful calls normally return a JSON object with a response key containing the method's result:

{ "response": { "status": "ok", "code": 0 } }

API exceptions return a top-level error string and may include a numeric code. Missing or invalid authentication returns HTTP 403, for example:

{ "error": "Not Logged In", "code": 403 }

Some methods report an unsuccessful operation inside response instead of raising an API exception. In particular, User/login can return HTTP 200 with response.status set to fail; see the 2FA example below. Clients must check the HTTP status, then a top-level error, then any method-specific result status. A successful HTTP status alone does not establish that login or a bulk operation succeeded.

For interactive exploration of all available endpoints, request/response schemas, and the ability to try calls directly from your browser, use the API Explorer at:

https://x4b.net/api-explorer/

Getting an API Key

API keys are managed from your X4B dashboard:

1. Navigate to Dashboard → Account Settings.
2. Click the API Keys tab.
3. Enter a descriptive Name for your key (e.g. "Monitoring Script" or "Terraform") and click Create Key.
4. The generated key is displayed once — copy and store it securely immediately. You will not be able to view it again.
5. To revoke a key, use the Action → Delete dropdown next to the key in the list.

You can create multiple API keys for different purposes and revoke them individually without affecting others.

Authentication

APIv2 supports the following authentication methods. Supply one credential per request. An API_KEY parameter takes precedence over the Bearer header; session authentication is used only when neither is supplied. Invalid explicit credentials do not fall back to the session.

1. Bearer Token (Recommended)

Include an Authorization header with your API key:

Authorization: Bearer api {your_api_key}

This is the preferred method for programmatic access. Example using curl:

curl -H "Authorization: Bearer api YOUR_API_KEY" \
     https://www.x4b.net/apiv2/Service/all

2. API_KEY Parameter

Pass your key as a POST or GET parameter named API_KEY:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "API_KEY=YOUR_API_KEY" \
     https://www.x4b.net/apiv2/Service/all

3. Session Cookie

When making requests from a browser where you are already logged into the X4B dashboard, your existing session cookie is used automatically. This is useful for testing in the API Explorer.

You may also login using the User::login api which attaches a Session cookie to the response.

Two-Factor Authentication (2FA)

Attempting password-based login will return:

{
  "response": {
    "status": "fail",
    "code": 4,
    "message": "2FA required. To authenticate with the API you must use an API key or disable 2FA."
  }
}

Common Patterns

Querying

Most modules support querying by field using the query[fieldname] parameter. Include the module's required scope fields from describe; for example, Port requires a service or lease ID even when looking up a port by ID:

GET /apiv2/Port/get?query[id]=1234&query[service]=5678

Pagination

List endpoints (all) support pagination via page[start] and page[limit]:

GET /apiv2/DnsRecord/all?page[start]=0&page[limit]=50

The default limit is 200 records. The maximum limit is also 200.

CRUD Operations

Modules that support write operations expose a standard set of methods:

Create and update operations accept a value[fieldname] parameter for each field. Update and delete operations require a query[id] to identify the target object.

Complete request examples

These equivalent read requests fetch port 1234 in service 5678. Replace both IDs with values belonging to your account and YOUR_API_KEY with your API key. Keep authentication in the header in new integrations.

GET query parameters (no request body or request Content-Type is needed):

curl --get 'https://www.x4b.net/apiv2/Port/get' \
     -H 'Authorization: Bearer api YOUR_API_KEY' \
     --data-urlencode 'query[id]=1234' \
     --data-urlencode 'query[service]=5678'

JSON POST body:

curl 'https://www.x4b.net/apiv2/Port/get' \
     -H 'Authorization: Bearer api YOUR_API_KEY' \
     -H 'Content-Type: application/json' \
     --data '{"query":{"id":1234,"service":5678}}'

URL-encoded POST body:

curl 'https://www.x4b.net/apiv2/Port/get' \
     -H 'Authorization: Bearer api YOUR_API_KEY' \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode 'query[id]=1234' \
     --data-urlencode 'query[service]=5678'

Multipart POST body (curl supplies the Content-Type and boundary):

curl 'https://www.x4b.net/apiv2/Port/get' \
     -H 'Authorization: Bearer api YOUR_API_KEY' \
     --form-string 'query[id]=1234' \
     --form-string 'query[service]=5678'

For writes, send POST to the write method. For example, these JSON and form requests both change the TTL of DNS record 1234 to 300 seconds. Replace the record ID with an existing record you intend to update.

curl 'https://www.x4b.net/apiv2/DnsRecord/update' \
     -H 'Authorization: Bearer api YOUR_API_KEY' \
     -H 'Content-Type: application/json' \
     --data '{"query":{"id":1234},"value":{"ttl":300}}'

curl 'https://www.x4b.net/apiv2/DnsRecord/update' \
     -H 'Authorization: Bearer api YOUR_API_KEY' \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode 'query[id]=1234' \
     --data-urlencode 'value[ttl]=300'

With multipart encoding, use --form-string 'query[id]=1234' --form-string 'value[ttl]=300' instead of the URL-encoded fields, and let curl set the multipart Content-Type. Use create with a value object containing the required fields from describe; use delete with a query object identifying the record.

Self-Documentation

Every module exposes a describe method that returns available methods and their parameters:

GET /apiv2/Port/describe

Available Modules

Below is a summary of the customer-facing API modules. For complete field-level detail, request/response schemas, and required parameters, use the API Explorer at https://x4b.net/api-explorer/.

Services & Infrastructure

DNS

Firewall & Security

SSL / TLS

HTTP

Tunnels

User Authentication Module

The User module provides session-based authentication endpoints.

Note: For automated API access, use API keys rather than the User/login method. The login endpoint is primarily intended for interactive sessions and does not work with 2FA-enabled accounts.

Rate Limits

API requests are subject to rate limiting. If you exceed the limit, you will receive an HTTP 429 response. Contact support if you need higher limits for your use case.

APIv1

APIv1 is deprecated since 01/09/2026 and scheduled for removal in 2027. Do not implement new functionality on APIv1.

Support

For questions about the API, open a support ticket via the dashboard or email support@x4b.net. When reporting an issue, include the HTTP method, endpoint, Request ID, response status, and a minimal redacted request and response example.

Remove API keys (including API_KEY query or body parameters and Authorization header values), session cookies, passwords, private keys, and sensitive customer payloads before sharing URLs, headers, bodies, logs or screenshots. Replace secret values with [REDACTED]; include only the fields needed to demonstrate the issue.

For example, a sanitized report can use placeholders rather than live credentials:

Method: GET
Endpoint: /apiv2/<Module>/<Method>?API_KEY=[REDACTED]
Authorization: Bearer [REDACTED]
Cookie: [REDACTED]
Request ID: <request ID from the response>
Response status: <HTTP status>
Request/response body: <minimal example with sensitive values replaced by [REDACTED]>