Managing security groups

A security group is a set of firewall rules applied to your instances. Each rule opens a protocol and port range to a source address range, in one direction.

Every operation on this page has been run against production, so the examples are the real requests and responses, not illustrations.

Authentication

Send your console API key in an Authorization header. The API does not accept cookie or session authentication — a request without the header returns:

{ "error": { "code": 401, "message": "Missing or invalid Authorization header" } }

export CL_KEY="clk_live_your_key_here"

1. Create a group

POST /security-group

curl -X POST https://console.cloudlogics.com/api/v1/security-group \
  -H "Authorization: Bearer $CL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "web-servers", "description": "Public web tier"}'

name is required, must be 3–50 characters, and may contain only a-z, 0-9 and hyphens. Uppercase is converted to lowercase. Omitting the name returns 400 with "name cannot be empty".

A new group has no inbound rules, so nothing can reach an instance using it until you add some. You can also pass a rules array here to create the group and its rules in one call, using the same rule shape as the next section.

Every field, with its allowed values, is listed on the operation page for this endpoint.

2. Add a rule

POST /security-group/{id}/rule

curl -X POST https://console.cloudlogics.com/api/v1/security-group/$GROUP_ID/rule \
  -H "Authorization: Bearer $CL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "direction": "ingress",
        "protocol": "tcp",
        "dst_port": "443",
        "ethertype": "IPv4",
        "remote_ip": "0.0.0.0/0",
        "description": "HTTPS from anywhere"
      }'

Returns 201 with the created rule:

{
  "data": {
    "id": "614eee70-0cc3-4d40-90aa-a023d77d7808",
    "security_group_id": "8f14e45f-ceea-467a-9f2c-1b1d3a5e77c2",
    "project_id": "739c7634e11841a18196db15428400aa",
    "name": null,
    "direction": "ingress",
    "protocol": "tcp",
    "port_range_min": 443,
    "port_range_max": 443,
    "ether_type": "IPv4",
    "remote_ip_prefix": "0.0.0.0/0",
    "normalized_cidr": "0.0.0.0/0",
    "remote_group_id": null,
    "remote_address_group_id": null,
    "description": "HTTPS from anywhere",
    "belongs_to_default_sg": false,
    "revision_number": 0,
    "created_at": "2026-09-08T20:26:02Z"
  }
}

Adding the same rule twice returns 409:

{ "error": { "code": 409, "message": "This rule already exists in the selected security group." } }

That makes the call safe to retry — a 409 means the rule you wanted is already in place.

The request and response use different names

This is the easiest mistake to make. You cannot send back what you read.

You send	You get back
dst_port: "443" (string)	port_range_min: 443, port_range_max: 443 (integers)
remote_ip: "0.0.0.0/0"	remote_ip_prefix, plus normalized_cidr
ethertype: "IPv4"	ether_type: "IPv4" (with an underscore)
:::

Rule fields

Field	Notes
direction	ingress for inbound, egress for outbound
protocol	lowercase — tcp, udp, icmp
dst_port	port or range, sent as a string ("443"). Omit for icmp.
ethertype	IPv4 or IPv6
remote_ip	CIDR. 0.0.0.0/0 is the whole internet; /32 is a single address.
remote_group	use instead of remote_ip to allow traffic from another security group
description	optional, but worth setting — it is what you read at 3am

A typical web tier ends up with:

Direction	Protocol	Port	Source	Purpose
ingress	tcp	443	0.0.0.0/0	HTTPS from anywhere
ingress	tcp	80	0.0.0.0/0	HTTP from anywhere
ingress	tcp	22	203.0.113.4/32	SSH from one address
ingress	icmp	—	10.0.0.0/24	ping from the private network

3. Inspect what you built

GET /security-group · GET /security-group/{id} · GET /security-group/{id}/rule

curl https://console.cloudlogics.com/api/v1/security-group/$GROUP_ID/rule \
  -H "Authorization: Bearer $CL_KEY"

The list view returns each group with its rule counts, so you can see at a glance which groups are actually doing something:

{
  "data": [
    {
      "ID": "8f14e45f-ceea-467a-9f2c-1b1d3a5e77c2",
      "Name": "web-servers",
      "Description": "Public web tier",
      "Project": "my-project",
      "ingress_rules": 3,
      "egress_rules": 0
    }
  ]
}

4. Delete a group

DELETE /security-group/{id}

curl -X DELETE https://console.cloudlogics.com/api/v1/security-group/$GROUP_ID \
  -H "Authorization: Bearer $CL_KEY"

Deleting a group removes its rules with it.

5. Attach a group to an instance

POST /server/{server_id}/security-group/{id}

curl -X POST \
  https://console.cloudlogics.com/api/v1/server/$SERVER_ID/security-group/$GROUP_ID \
  -H "Authorization: Bearer $CL_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Returns 200:

{ "data": "security group attached successfully" }

The last path segment is the group’s UUID, not its name

$GROUP_ID is the ID you get back from GET /security-group — for example 8f14e45f-ceea-467a-9f2c-1b1d3a5e77c2. Passing the group name (web-servers) does not resolve.

The request body is an empty JSON object. Both identifiers travel in the path.

To see what is already attached, use GET /server/{server_id}/security-group.

6. Detach a group

DELETE /server/{server_id}/security-group/{id}

curl -X DELETE \
  https://console.cloudlogics.com/api/v1/server/$SERVER_ID/security-group/$GROUP_ID \
  -H "Authorization: Bearer $CL_KEY"

Detaching leaves the group itself intact — it only removes it from that one instance.

Doing the same thing in the console

Everything above is also available under Network & Security → Security Groups, and a group can be attached or detached from an instance’s own page with Add Security Group. The console is the quickest way to check your work while you are getting the API calls right.