Official integration guide

Integrate Cloud247 API from authentication to webhooks

An English guide to ordering, service renewal, addon purchase and status-event delivery. The complete request and response contract is available in the OpenAPI reference at the end of this page.

Base URL https://api.cloud247.vn/v1
Authentication Authorization: Bearer <token>
Successful response {"data": {...}}

Quick start

Three steps to call the API

The API does not use Portal sessions, cookies or CSRF. Except for token issuance, every request uses a Bearer token and returns JSON.

1

Issue a scoped token

Call POST /auth/tokens with an email address or username. Request only the abilities your application needs and store the token as a secret.

2

Discover context and options

Use GET /context, product details and service options to discover valid locales, currencies, cycles, addons, datacenters and operating systems.

3

Submit safe mutations

Generate one Idempotency-Key per operation. Quotes are optional; send their fingerprint when the submitted price must match a price you displayed.

Every successful JSON response has a data key. Paginated collections also contain links and meta; errors use application/problem+json and are not wrapped in data.

Integration flow

Contracts to preserve

Language and currency

Send Accept-Language: vi or en to select the response language. Send X-Currency for request context, catalog prices and new-order checkout; it is required by POST /order-quotes and POST /orders. Existing services and persisted commerce resources use their stored currency.

Display fees and service policies

GET /context also returns data.settings. fees contains the fee per changed IP, the ownership transfer fee and the wallet transfer percentage charged to the sender. Both operation fees exclude tax; use the operation quote for the final charge.

service_policy describes renewal, suspension and expiry retention, the continuous registered term required to unlock VM benefits, and the wait before automatic refunds for eligible failed provisioning. Durations are in minutes. Retention runs from expiry and applies only when expired_termination.enabled is true. These are general policies; actual timing depends on the service. The automatic refund delay is not a trial period.

Order creation

Read GET /catalog/products/{product} once for the selected currency. The response contains all-cycle product and addon pricing plus the applicable datacenter and operating-system choices in configuration_options. When the billing cycle changes, select pricing with the matching billing_cycle_id from that response instead of calling the API again. Submit its option and addon IDs in the quote or order body. POST /order-quotes is optional, while POST /orders always recalculates the price immediately before creating an order. One request may combine multiple VM, Hosting and Proxy products in items; the top-level promotion_code applies to the complete order.

Every items[] entry must send exactly qty entries in units. Each VM requires a hostname; each Hosting unit requires a domain and username in items[].units[].configuration. A Hosting username must start with a lowercase letter, contain only lowercase letters and digits, and be 3–16 characters long. Its first eight characters must be unique.

items[].configuration.password is the default password for every service in that item. Send items[].units[].configuration.password only when one unit needs its own password. If it is omitted or sent as null, that unit inherits the default password.

A quote only checks current VM hostname and Hosting domain and username availability; it does not hold those values. POST /orders atomically holds the effective values when creating the order, including while payment is pending. A pending order's holds are released when it expires or is cancelled. A payment retry rechecks availability before charging if an expired hold must be restored.

Renewals and addon purchases

Renewal uses target_billing_cycle_id. Addon purchase only increments quantities using addons[].addon_id and qty; it does not change the main plan's billing cycle or due date. Read GET /services/{service}/upgrade-options for current quantity limits.

Idempotency and quote fingerprints

  • The partner generates each Idempotency-Key. Reuse it only to retry the same logical request; use a new key for a new operation.
  • Quote-Fingerprint is optional for orders, renewals and addon purchases. When supplied, a price or configuration change returns 409 quote_changed.
  • Omitting the fingerprint means accepting the price recalculated when the mutation is submitted.

Webhooks

Register a public HTTPS URL with POST /webhooks and store the returned whsec_* immediately because it is shown once. Receivers must verify the HMAC over the raw body, reject stale timestamps, and deduplicate by the id field in the verified JSON body; they may also require the event-ID header to match the body.

Laravel 12

Integration code samples

These examples use Laravel HTTP Client. Copy them and replace IDs, tokens and URLs with values from your account.

1a. Add the Cloud247 configuration · Add to the returned array in config/services.php
'cloud247' => [
    'base_url' => env('CLOUD247_API_URL', 'https://api.cloud247.vn/v1'),
    'token' => env('CLOUD247_API_TOKEN'),
    'locale' => env('CLOUD247_API_LOCALE', 'vi'),
    'currency' => env('CLOUD247_API_CURRENCY', 'VND'),
    'webhook_secret' => env('CLOUD247_WEBHOOK_SECRET'),
],
1b. Create a shared HTTP client · app/Services/Cloud247Api.php
<?php

namespace App\Services;

use Illuminate\Http\Client\PendingRequest;
use Illuminate\Support\Facades\Config;
use Illuminate\Support\Facades\Http;

final class Cloud247Api
{
    /**
     * @param array<string, string> $headers
     */
    public function request(array $headers = []): PendingRequest
    {
        return Http::baseUrl(
            rtrim(Config::string('services.cloud247.base_url'), '/') . '/',
        )
            ->acceptJson()
            ->asJson()
            ->withToken(Config::string('services.cloud247.token'))
            ->withHeaders([
                'Accept-Language' => Config::string('services.cloud247.locale'),
                ...$headers,
            ])
            ->timeout(30);
    }

    /**
     * @param array<string, string> $headers
     */
    public function pricedRequest(array $headers = []): PendingRequest
    {
        return $this->request([
            'X-Currency' => Config::string('services.cloud247.currency'),
            ...$headers,
        ]);
    }
}
2. Issue an API token · The plaintext token is returned once
<?php

use Illuminate\Support\Facades\Http;

$issued = Http::baseUrl('https://api.cloud247.vn/v1/')
    ->acceptJson()
    ->asJson()
    ->post('auth/tokens', [
        'identifier' => 'customer@example.com',
        'password' => 'your-password',
        'device_name' => 'Production integration',
        'abilities' => [
            'catalog:read',
            'orders:create',
            'orders:read',
            'services:read',
            'services:renew',
            'services:upgrade',
            'webhooks:manage',
        ],
    ])
    ->throw()
    ->json('data');

// Store this value securely. It cannot be retrieved again.
$accessToken = $issued['access_token'];
3. Read a product, optionally quote, and create an order · Quote-Fingerprint is optional
<?php

use App\Services\Cloud247Api;
use Illuminate\Support\Str;

$api = app(Cloud247Api::class);
$productId = 12;
$billingCycleId = 3;

// X-Currency is used only for request context, catalog, and new-order checkout requests.
// One response contains all-cycle product/addon pricing and configuration options.
$product = $api->pricedRequest()
    ->get("catalog/products/{$productId}")
    ->throw()
    ->json('data');

// On cycle changes, select matching rows from $product['pricings'] and
// $product['addons'][*]['pricings']; do not request the catalog again.

$orderPayload = [
    'items' => [
        [
            'product_id' => $productId,
            'billing_cycle_id' => $billingCycleId,
            'qty' => 2,
            'auto_renew' => true,
            'configuration' => [
                // Required default password; a unit may override it.
                'password' => 'ChangeMe-Strong-Password',
                'datacenter_id' => 2,
                'operating_system_id' => 5,
            ],
            'units' => [
                [
                    'configuration' => ['hostname' => 'api-vm-01.example.com'],
                ],
                [
                    'configuration' => [
                        'hostname' => 'api-vm-02.example.com',
                        'password' => 'A-Different-Strong-Password',
                    ],
                ],
            ],
            'addons' => [
                ['addon_id' => 8, 'qty' => 2],
            ],
        ],
    ],
    // One code applies to the complete multi-product order.
    'promotion_code' => null,
];

$lockDisplayedPrice = true;
$fingerprint = $lockDisplayedPrice
    ? $api->pricedRequest()
        ->post('order-quotes', $orderPayload)
        ->throw()
        ->json('data.quote_fingerprint')
    : null;

$headers = ['Idempotency-Key' => (string) Str::uuid()];

if (is_string($fingerprint)) {
    $headers['Quote-Fingerprint'] = $fingerprint;
}

$order = $api->pricedRequest($headers)
    ->post('orders', $orderPayload)
    ->throw()
    ->json('data');
4. Renew a service and purchase addons · Preview and mutation use the same payload
<?php

use App\Services\Cloud247Api;
use Illuminate\Support\Str;

$api = app(Cloud247Api::class);
$serviceId = 123;

// Renewal
$renewalPayload = [
    'target_billing_cycle_id' => 3,
    'promotion_code' => null,
];

$renewalFingerprint = $api->request()
    ->post("services/{$serviceId}/renewals/preview", $renewalPayload)
    ->throw()
    ->json('data.quote_fingerprint');

$renewal = $api->request([
    'Idempotency-Key' => (string) Str::uuid(),
    'Quote-Fingerprint' => $renewalFingerprint,
])
    ->post("services/{$serviceId}/renewals", $renewalPayload)
    ->throw()
    ->json('data');

// Addon purchase: qty is the additional quantity.
$upgradeOptions = $api->request()
    ->get("services/{$serviceId}/upgrade-options")
    ->throw()
    ->json('data');

$addonPayload = [
    'addons' => [
        ['addon_id' => 8, 'qty' => 2],
    ],
    'promotion_code' => null,
];

$addonFingerprint = $api->request()
    ->post("services/{$serviceId}/upgrades/preview", $addonPayload)
    ->throw()
    ->json('data.quote_fingerprint');

$operation = $api->request([
    'Idempotency-Key' => (string) Str::uuid(),
    'Quote-Fingerprint' => $addonFingerprint,
])
    ->post("services/{$serviceId}/upgrades/addons", $addonPayload)
    ->throw()
    ->json('data');
5a. Register a webhook · The secret is returned once
<?php

use App\Services\Cloud247Api;

$api = app(Cloud247Api::class);

// Register once. Persist data.secret encrypted because it is shown once.
$endpoint = $api->request()
    ->post('webhooks', [
        'name' => 'Production events',
        'url' => 'https://partner.example.com/api/webhooks/cloud247',
        'events' => [
            'order.updated',
            'invoice.updated',
            'service.updated',
            'service.operation.updated',
            'wallet.balance.updated',
        ],
    ])
    ->throw()
    ->json('data');

$signingSecret = $endpoint['secret'];
5b. Define the webhook route · routes/api.php
<?php

use App\Http\Controllers\Cloud247WebhookController;
use Illuminate\Support\Facades\Route;

Route::post('webhooks/cloud247', Cloud247WebhookController::class);
5c. Verify and process webhooks · Verify the raw request body
<?php

namespace App\Http\Controllers;

use App\Jobs\ProcessCloud247Webhook;
use Illuminate\Http\Request;
use Illuminate\Http\Response;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Config;
use Throwable;

final class Cloud247WebhookController
{
    public function __invoke(Request $request): Response
    {
        $timestamp = $request->header('X-Cloud247-Timestamp');
        $signature = $request->header('X-Cloud247-Signature');

        abort_unless(
            is_string($timestamp)
                && ctype_digit($timestamp)
                && is_string($signature),
            401,
        );

        abort_if(abs(now()->timestamp - (int) $timestamp) > 300, 401);

        $expected = 'v1=' . hash_hmac(
            'sha256',
            $timestamp . '.' . $request->getContent(),
            Config::string('services.cloud247.webhook_secret'),
        );

        abort_unless(hash_equals($expected, $signature), 401);

        $payload = $request->json()->all();
        $eventId = data_get($payload, 'id');
        $eventType = data_get($payload, 'type');

        abort_unless(
            is_string($eventId)
                && $eventId !== ''
                && is_string($eventType)
                && $eventType !== ''
                && $request->header('X-Cloud247-Event-Id') === $eventId
                && $request->header('X-Cloud247-Event') === $eventType,
            401,
        );

        $dedupeKey = "cloud247:webhook:{$eventId}";

        if (! Cache::add($dedupeKey, true, now()->addDays(7))) {
            return response()->noContent();
        }

        try {
            ProcessCloud247Webhook::dispatch(
                eventId: $eventId,
                type: $eventType,
                payload: $payload,
            );
        } catch (Throwable $exception) {
            Cache::forget($dedupeKey);

            throw $exception;
        }

        return response()->noContent();
    }
}
In production, prefer an inbox table with a unique event-ID index over cache when deduplication must survive deployments and cache flushes.

Proxy · API

Purchase and manage Proxy through the API

Find available plans with GET /v1/catalog/products?type=proxy, then read the product detail for billing cycles, protocols and supported authentication modes. Use the shared flow POST /v1/order-quotes → POST /v1/orders → POST /v1/orders/{order}/payments. Pricing and provisioning availability are validated by the server; a quote does not reserve capacity.

The example is one element of items; replace product and cycle IDs with catalog values. Each units entry represents one Proxy. Omit username/password for ip_allowlist. Both combined modes require credentials and an IP allowlist.

Configure one Proxy
{
  "product_id": 123,
  "billing_cycle_id": 1,
  "qty": 1,
  "auto_renew": false,
  "configuration": {
    "protocol": "http",
    "auth_mode": "userpass_and_ip_allowlist",
    "password": "Example-Only-ChangeMe!42"
  },
  "units": [{
    "configuration": {
      "username": "customer_proxy01",
      "allowed_cidrs": ["203.0.113.10/32"]
    }
  }],
  "addons": []
}

userpass · ip_allowlist · userpass_and_ip_allowlist · userpass_or_ip_allowlist

AND requires both valid credentials and an allowed IP; OR accepts either. Select only modes and protocols supported by the plan.

Shared service endpoints

{service} always identifies a Plus service, not a Proxy detail row or an upstream service. For example, GET /v1/services/123 returns shared fields and the type-specific data.detail. For Proxy, this already includes connection settings, configuration and recorded runtime information. A separate GET /v1/services/123/proxy detail endpoint is neither required nor provided.

EndpointPurpose / ability
GET /v1/services/{service}Read full service details, including the type-specific data.detail · services:read
GET /v1/services/{service}/maintenance-optionsSupported actions and availability reasons · services:read
GET /v1/services/{service}/operations
GET /v1/services/{service}/operations/{operation}
Track operations, including Proxy IP or access changes · services:read

Proxy-specific endpoints

The /proxy/ group contains Proxy runtime status and type-specific operations. The shared service endpoints above remain available.

EndpointPurpose / ability
GET /v1/services/{service}/proxy/statusPoll cached runtime status; may schedule an eligible background refresh · services:read
GET /v1/services/{service}/proxy/rotations/quote
POST /v1/services/{service}/proxy/rotations
Quote and request an IP change when supported · services:control
POST /v1/services/{service}/proxy/access-configurationsUpdate username, new_password or allowed_cidrs for the current mode · services:control

/proxy/status returns the stored snapshot and throttles background refreshes. It does not call the upstream service inline, rotate the IP or guarantee fresh data on this request. Use GET /v1/services/{service} for plan, due date and full service details.

Example: change the IP of service 123

  1. Read GET /v1/services/123/maintenance-options to check that an IP change is available.
  2. Get a quote with GET /v1/services/123/proxy/rotations/quote.
  3. Send POST /v1/services/123/proxy/rotations with an Idempotency-Key and the unexpired accepted_quote. The 202 response identifies the operation in data.operation.id.
  4. If the operation ID is 456, poll GET /v1/services/123/operations/456. After completion, read service details or Proxy status again for current connection information. Handle failed operations; 202 alone does not mean the IP changed successfully.

Each rotation/access POST requires Idempotency-Key. Retry the same key and body after a lost response. Paid rotations require the quoted accepted_quote. Do not submit an IP selection. To retain the password, omit new_password instead of sending an empty string.

202 means accepted, not completed; track the operation to completion. New services activate and capture payment only after readiness is confirmed. A transient unknown runtime status does not mean cancellation. Connect to endpoint; egress_ip is the observed outbound IP.

Proxy shares the automatic-renewal, renewal quote/execute and termination APIs. VM/Hosting actions, addon upgrades and ownership transfers are not supported for Proxy. Every endpoint is account-owned. The actual password is in detail.password_hint on detail/status; Proxy API lists omit password and allowlist.

VM console · noVNC

Embed a VNC console on your website

Request console details from the API, then use noVNC on your website to connect through Cloud247 WebSockets.

Call POST /v1/services/{service}/maintenance/console-sessions from your backend with a Bearer token carrying services:control. The account must have services.control permission and own the service. No body, Portal cookies, CSRF or Idempotency-Key is required.

Keep the API token on your backend. Verify that your signed-in customer can control the service before sending its console ticket to the browser. Console URLs, tickets and passwords are secrets: do not log or publicly cache them.

1. Fetch the console ticket on your backend
curl --request POST \
  'https://api.cloud247.vn/v1/services/123/maintenance/console-sessions' \
  --header 'Authorization: Bearer <API_TOKEN>' \
  --header 'Accept: application/json'
Laravel HTTP Client · backend
<?php

use Illuminate\Support\Facades\Http;

// Authorize the signed-in customer's access to this service first.
$serviceId = 123;
$console = Http::baseUrl('https://api.cloud247.vn/v1')
    ->withToken(config('services.cloud247.token'))
    ->acceptJson()
    ->post("services/{$serviceId}/maintenance/console-sessions")
    ->throw()
    ->json('data');
Response fieldUsage
data.endpoint.web_urlComplete WebSocket URL including its token. Pass it unchanged to noVNC.
data.endpoint.web_url_fallbackAlternative URL when the primary connection fails. Use the returned URL unchanged.
data.endpoint.passwordConsole password, passed to noVNC as credentials.password.
data.session.expires_at
data.endpoint.ttl_seconds
Ticket expiry (ISO 8601) and remaining lifetime in seconds.
data.endpoint.connection_typeUse noVNC for native_vnc. webmks/vmrc needs the corresponding client. Check the fields you need, as some may be null.

Use Cloud247 WebSockets

Install @novnc/novnc in your frontend; you do not need to run your own WebSocket server. This example uses a bundler such as Vite and a #console element with an explicit height.

2. noVNC · JavaScript
import RFB from '@novnc/novnc/core/rfb.js';

// consoleData = response.data from your authorized backend
const { endpoint, session } = consoleData;
if (endpoint.connection_type !== 'native_vnc' || !endpoint.web_url) {
    throw new Error('A native VNC WebSocket endpoint is required');
}
if (session.expires_at && Date.parse(session.expires_at) <= Date.now()) {
    throw new Error('Fetch a fresh console ticket before connecting');
}

const screen = document.getElementById('console');
screen.style.height = '70vh';
const rfb = new RFB(screen, endpoint.web_url, {
    shared: true,
    credentials: { password: endpoint.password },
});
rfb.scaleViewport = true;
rfb.addEventListener('credentialsrequired', () => {
    rfb.sendCredentials({ password: endpoint.password });
});
// Optional toolbar: rfb.sendCtrlAltDel();
// When closing/unmounting the console: rfb.disconnect();

If the primary connection fails, disconnect the old instance and try web_url_fallback when present. HTTPS websites need WSS; if using CSP, allow the returned WebSocket host/port in connect-src. Backend API calls do not require browser API CORS access.

Expiry and reconnecting

Read expires_at and ttl_seconds in the response for the ticket lifetime. Before reconnecting after expiry, call the endpoint again for valid details. The API may reuse an existing ticket; do not assume every request rotates it or extends its lifetime. Always use the URL and password from the latest response.

For 401/403 check authentication and permissions; 404 means no owned service was found; 422 means an unsupported, locked, suspended, expired or currently unavailable console. For 429, respect Retry-After instead of retrying continuously.

noVNC API

Advanced integration — own WebSocket server or desktop VNC

Run your own WebSocket server or use a desktop VNC client

Use endpoint.host, endpoint.port and endpoint.password from the response. Your server must be able to connect over TCP to that host and port. The host is a hostname, without https://. Refresh the connection details with each new ticket instead of hard-coding a host or port.

You can run a WebSocket server using websockify, forwarding to endpoint.host:endpoint.port, then connect noVNC to your own WSS endpoint using endpoint.password. Do not point noVNC directly at the raw VNC TCP port or turn that port into a WSS URL. Desktop VNC clients use the host, port and password directly.

Single-session WebSocket server example
# Replace host and port with the current API response.
nc -vz -w 5 console.cloud247.vn 31726

websockify --ssl-only \
  --cert=/path/to/fullchain.pem --key=/path/to/privkey.pem \
  0.0.0.0:6080 console.cloud247.vn:31726
# noVNC URL on your website: wss://your-console.example.com:6080/

This websockify example maps one target. For multiple VMs, use per-session token routing and update targets when the API issues new ports. TLS on your websockify protects the browser-to-partner hop; the Cloud247 native TCP port does not add TLS. Prefer Cloud247 WSS for a simpler browser integration.

websockify

OpenAPI 3.1

Endpoint reference

Explore request bodies, parameters and response schemas, or try requests with a Bearer token.

Endpoint and field names remain in English so the integration contract stays stable.
Cloud247 API v1 · https://api.cloud247.vn/v1 OpenAPI 3.1 · Bearer Auth · JSON