---
title: Create Firewall Rule
description: "Creates a new firewall rule on the server. Synchronous — runs InstallFirewall over SSH inline and returns the new row at 201. Idempotent on (name, port, ip_address). Requires the write:servers…"
url: "https://betterdocs.shahrear.msf.bd/index.php/docs/hell0-boys-docs/hell0-boys/servers/create-firewall-rule/"
updated: "2026-08-20"
category: hell0 boys / Servers
---

# Create Firewall Rule

POST`/servers/{uuid}/firewall-rules`

## Code Samples

```curl

                curl --request POST \
  --url 'https://app.xcloud.host/api/v1/servers/{uuid}/firewall-rules' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "ssh-office",
    "port": "22",
    "ip_address": "203.0.113.10",
    "protocol": "tcp",
    "traffic": "allow"
}'

                const response = await fetch('https://app.xcloud.host/api/v1/servers/{uuid}/firewall-rules', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "name": "ssh-office",
    "port": "22",
    "ip_address": "203.0.113.10",
    "protocol": "tcp",
    "traffic": "allow"
})
});

const data = await response.json();
console.log(data);

                import requests

headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}

payload = {
    "name": "ssh-office",
    "port": "22",
    "ip_address": "203.0.113.10",
    "protocol": "tcp",
    "traffic": "allow"
}

response = requests.post("https://app.xcloud.host/api/v1/servers/{uuid}/firewall-rules", headers=headers, json=payload)

print(response.json())

                <?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://app.xcloud.host/api/v1/servers/{uuid}/firewall-rules',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => [
  'Authorization: Bearer YOUR_TOKEN',
  'Content-Type: application/json'
  ],
  CURLOPT_POSTFIELDS => '{
    "name": "ssh-office",
    "port": "22",
    "ip_address": "203.0.113.10",
    "protocol": "tcp",
    "traffic": "allow"
}',
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

                using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://app.xcloud.host/api/v1/servers/{uuid}/firewall-rules");
request.Headers.Add("Authorization", "Bearer YOUR_TOKEN");
request.Content = new StringContent(@"{
    ""name"": ""ssh-office"",
    ""port"": ""22"",
    ""ip_address"": ""203.0.113.10"",
    ""protocol"": ""tcp"",
    ""traffic"": ""allow""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);

                import java.net.URI;
import java.net.http.*;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://app.xcloud.host/api/v1/servers/{uuid}/firewall-rules"))
    .header("Authorization", "Bearer YOUR_TOKEN")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
{
    "name": "ssh-office",
    "port": "22",
    "ip_address": "203.0.113.10",
    "protocol": "tcp",
    "traffic": "allow"
}
"""))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```

## Response

```json

                {
    "success": true,
    "message": "Operation completed successfully.",
    "data": {
        "uuid": "55ff66aa-77bb-88cc-99dd-00ee11ff2233",
        "name": "ssh-admin",
        "ip_address": "203.0.113.10",
        "port": "22",
        "protocol": "tcp",
        "traffic": "allow",
        "is_active": true,
        "description": "Office static IP",
        "created_at": "2024-01-15T09:30:00Z",
        "updated_at": "2024-01-15T09:30:00Z"
    }
}

                {
    "success": false,
    "message": "Unauthenticated.",
    "data": null
}

                {
    "success": false,
    "message": "This action is unauthorized. Your token is missing the required scope.",
    "data": null
}

                {
    "success": false,
    "message": "Not found.",
    "data": null
}

                {
    "success": false,
    "message": "An error occurred.",
    "data": null
}
```

Creates a [New](https://betterdocs.shahrear.msf.bd/encyclopedia/new/) firewall rule on the [Server](https://betterdocs.shahrear.msf.bd/encyclopedia/server/). Synchronous — runs `InstallFirewall` over SSH inline and returns the [New](https://betterdocs.shahrear.msf.bd/encyclopedia/new/) row at 201. Idempotent on (name, port, ip_address). Requires the `write:servers` scope.

## Path Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `uuid` | string (uuid) | **Required** | UUID of the [Server](https://betterdocs.shahrear.msf.bd/encyclopedia/server/) |

## Request Body

Content type: `application/json` — **required**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | **Required** |  |
| `port` | string | Optional | Empty for all ports, a single port (e.g. \`22\`), or a range (e.g. \`8000:9000\`). Port ranges require \`protocol\` to be \`tcp\` or \`udp\` (not \`any\`). |
| `ip_address` | string | Optional | Comma-separated IPv4 addresses with optional \`/CIDR\` (e.g. \`203.0.113.10,198.51.100.0/24\`). Empty matches all IPs. |
| `protocol` | string | **Required** | Allowed: any, tcp, udp |
| `traffic` | string | **Required** | Allowed: allow, deny |

```json

                {
    "name": "ssh-office",
    "port": "22",
    "ip_address": "203.0.113.10",
    "protocol": "tcp",
    "traffic": "allow"
}
```

## Responses

### 201 — Firewall rule created

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `success` | boolean | Optional |  |
| `message` | string | Optional |  |
| `data` | object | Optional |  |
| `data` | object | Optional |  |
| `data.uuid` | string (uuid) | Optional |  |
| `data.name` | string | Optional |  |
| `data.ip_address` | string | Optional |  |
| `data.port` | string | Optional | Single port or comma/range list as configured (e.g. "22", "80,443", "8000-9000"). |
| `data.protocol` | string | Optional | Allowed: any, tcp, udp |
| `data.traffic` | string | Optional | Allowed: allow, deny |
| `data.is_active` | boolean | Optional |  |
| `data.description` | string | Optional |  |
| `data.created_at` | string (date-time) | Optional |  |
| `data.updated_at` | string (date-time) | Optional |  |

```json

                {
    "success": true,
    "message": "Operation completed successfully.",
    "data": {
        "uuid": "55ff66aa-77bb-88cc-99dd-00ee11ff2233",
        "name": "ssh-admin",
        "ip_address": "203.0.113.10",
        "port": "22",
        "protocol": "tcp",
        "traffic": "allow",
        "is_active": true,
        "description": "Office static IP",
        "created_at": "2024-01-15T09:30:00Z",
        "updated_at": "2024-01-15T09:30:00Z"
    }
}
```

### 401 — Missing or invalid authentication token

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `success` | boolean | Optional |  |
| `message` | string | Optional |  |
| `data` | object | Optional |  |

```json

                {
    "success": false,
    "message": "Unauthenticated.",
    "data": null
}
```

### 403 — Token lacks the required scope

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `success` | boolean | Optional |  |
| `message` | string | Optional |  |
| `data` | object | Optional |  |

```json

                {
    "success": false,
    "message": "This action is unauthorized. Your token is missing the required scope.",
    "data": null
}
```

### 404 — Resource not found or not accessible to your [Team](https://betterdocs.shahrear.msf.bd/encyclopedia/team/)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `success` | boolean | Optional |  |
| `message` | string | Optional |  |
| `data` | object | Optional |  |

```json

                {
    "success": false,
    "message": "Not found.",
    "data": null
}
```

### 422 — Validation failure or InstallFirewall SSH error.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `success` | boolean | Optional |  |
| `message` | string | Optional |  |
| `data` | object | Optional |  |

```json

                {
    "success": false,
    "message": "An error occurred.",
    "data": null
}
```