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.
Official integration guide
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.
https://api.cloud247.vn/v1
Authorization: Bearer <token>
{"data": {...}}
Quick start
The API does not use Portal sessions, cookies or CSRF. Except for token issuance, every request uses a Bearer token and returns JSON.
Call POST /auth/tokens with an email address or
username. Request only the abilities your application needs and
store the token as a secret.
Use GET /context, product details and service
options to discover valid locales, currencies, cycles, addons,
datacenters and operating systems.
Generate one Idempotency-Key per operation. Quotes
are optional; send their fingerprint when the submitted price
must match a price you displayed.
data key. Paginated
collections also contain links and meta; errors
use application/problem+json and are not wrapped in
data.
Integration flow
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.
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.
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.
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-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.
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
These examples use Laravel HTTP Client. Copy them and replace IDs, tokens and URLs with values from your account.
'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'),
],
<?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,
]);
}
}
<?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'];
<?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');
<?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');
<?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'];
<?php
use App\Http\Controllers\Cloud247WebhookController;
use Illuminate\Support\Facades\Route;
Route::post('webhooks/cloud247', Cloud247WebhookController::class);
<?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();
}
}
Proxy · 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.
{
"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.
{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.
| Endpoint | Purpose / ability |
|---|---|
GET /v1/services/{service} | Read full service details, including the type-specific data.detail · services:read |
GET /v1/services/{service}/maintenance-options | Supported actions and availability reasons · services:read |
GET /v1/services/{service}/operationsGET /v1/services/{service}/operations/{operation} | Track operations, including Proxy IP or access changes · services:read |
The /proxy/ group contains Proxy runtime status and type-specific operations. The shared service endpoints above remain available.
| Endpoint | Purpose / ability |
|---|---|
GET /v1/services/{service}/proxy/status | Poll cached runtime status; may schedule an eligible background refresh · services:read |
GET /v1/services/{service}/proxy/rotations/quotePOST /v1/services/{service}/proxy/rotations | Quote and request an IP change when supported · services:control |
POST /v1/services/{service}/proxy/access-configurations | Update 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.
GET /v1/services/123/maintenance-options to check that an IP change is available.GET /v1/services/123/proxy/rotations/quote.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.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
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.
curl --request POST \
'https://api.cloud247.vn/v1/services/123/maintenance/console-sessions' \
--header 'Authorization: Bearer <API_TOKEN>' \
--header 'Accept: application/json'
<?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 field | Usage |
|---|---|
data.endpoint.web_url | Complete WebSocket URL including its token. Pass it unchanged to noVNC. |
data.endpoint.web_url_fallback | Alternative URL when the primary connection fails. Use the returned URL unchanged. |
data.endpoint.password | Console password, passed to noVNC as credentials.password. |
data.session.expires_atdata.endpoint.ttl_seconds | Ticket expiry (ISO 8601) and remaining lifetime in seconds. |
data.endpoint.connection_type | Use noVNC for native_vnc. webmks/vmrc needs the corresponding client. Check the fields you need, as some may be null. |
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.
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.
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.
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.
# 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.
OpenAPI 3.1
Explore request bodies, parameters and response schemas, or try requests with a Bearer token.