Getting StartedExamplesImagesInstancesSSH KeysSecurity GroupsCreate security groupsUpdate security groupsList security groupsGet security groupDelete a security groupExamples (cURL)SnapshotsVolumes

A security group is a set of firewall rules on a set of instances. Security groups enable to create rules that either drop or allow incoming traffic from certain ports of your instances.

Create security groups

To create a new security group, send a request to:

POST /compute/v1/security-groups (HTTP 201 - Created)

The attribute values that must be set to successfully create a security group are:

Body parameters

  • name String Required - The human-readable name set for the security group.
  • description String Optional - The human-readable description set for the security group.
  • rules Array Required - The list of rules of the security group.

Rule object

  • protocol String Required - The protocol of the rule. Possible values are icmp, tcp, udp and all.
  • direction String Required - The direction of the rule. Possible values are ingress or egress.
  • port_range_min Integer Required - The port_range_min of the rule (e.g. 8080). Optional for icmp protocol.
  • port_range_max Integer Required - The port_range_min of the rule (e.g. 8085). Optional for icmp protocol.
{
   "name":"<security group name>",
   "description":"<security group description>",
   "rules":[
      {
         "protocol":"icmp",
         "port_range_min":null,
         "port_range_max":null,
         "direction":"ingress"
      },
      {
         "protocol":"tcp",
         "port_range_min":22,
         "port_range_max":22,
         "direction":"ingress"
      },
      {
         "protocol":"tcp",
         "port_range_min":8080,
         "port_range_max":8085,
         "direction":"ingress"
      },
      {
         "protocol":"all",
         "port_range_min":null,
         "port_range_max":null,
         "direction":"egress"
      }
   ]
}

Body response

The security group will be created using the provided information. The response body will contain a JSON object with standard attributes for your new security group:

  • id String - A unique identifier for each security group. This is automatically generated.
  • name String - The human-readable name set for the security group.
  • description String - The human-readable description set for the security group.
  • status String - The security group status. Possible values are enqueued, creating, created, updating, deleting and error.
  • rules Array - The security group rules.
  • created_at String - A time value given in ISO8601 combined date and time format that represents when the security group was created.
{
   "security_group":{
      "id":"<security group id>",
      "name":"<security group name>",
      "description":"<security group description>",
      "status":"creating",
      "rules":[
         {
            "protocol":"icmp",
            "port_range_min":null,
            "port_range_max":null,
            "direction":"ingress"
         },
         {
            "protocol":"tcp",
            "port_range_min":22,
            "port_range_max":22,
            "direction":"ingress"
         },
         {
            "protocol":"tcp",
            "port_range_min":8080,
            "port_range_max":8085,
            "direction":"ingress"
         },
         {
            "protocol":"all",
            "port_range_min":null,
            "port_range_max":null,
            "direction":"egress"
         }
      ],
      "created_at":"2020-03-20T15:17:42.375Z"
   }
}

Update security groups

To update a new security group, send a request to:

PUT /compute/v1/security-groups/<security_group_id> (HTTP 200)

The attribute values that must be set to successfully create a security group are:

Body parameters

  • name String Required - The human-readable name set for the security group.
  • description String Optional - The human-readable description set for the security group.
  • rules Array Required - The list of rules of the security group.

Rule object

  • protocol String Required - The protocol of the rule. Possible values are icmp, tcp, udp and all.
  • direction String Required - The direction of the rule. Possible values are ingress or egress.
  • port_range_min Integer Required - The port_range_min of the rule (e.g. 8080). Optional for icmp protocol and null for all ports.
  • port_range_max Integer Required - The port_range_min of the rule (e.g. 8085). Optional for icmp protocol and null for all ports.
{
   "name":"<security group name>",
   "description":"<security group description>",
   "rules":[
      {
         "protocol":"icmp",
         "port_range_min":null,
         "port_range_max":null,
         "direction":"ingress"
      }
   ]
}

Body response

The security group will be created using the provided information. The response body will contain a JSON object with standard attributes for your new security group:

  • id String - A unique identifier for each security group. This is automatically generated.
  • name String - The human-readable name set for the security group.
  • description String - The human-readable description set for the security group.
  • status String - The security group status. Possible values are enqueued, creating, created, updating, deleting and error.
  • rules Array - The security group rules.
  • created_at String - A time value given in ISO8601 combined date and time format that represents when the security group was created.
{
   "security_group":{
      "id":"<security group id>",
      "name":"<security group name>",
      "description":"<security group description>",
      "status":"creating",
      "rules":[
         {
            "protocol":"icmp",
            "port_range_min":null,
            "port_range_max":null,
            "direction":"ingress"
         }
      ],
      "created_at":"2020-03-20T15:17:42.375Z"
   }
}

List security groups

List all security groups available in an account.

GET /compute/v1/security-groups (HTTP 200 - OK)

Query parameters

  • per_page Integer Optional - A positive integer lower than or equal to 100 to select the number of items to return (default: 50).
  • page Integer Optional - A positive integer to choose the page to return.

Response body

The response will be a JSON object with pagination details and a key called security_groups. This will be set to an array of security group objects, each of which will contain the security group object:

  • id String - A unique identifier that can be used to reference a specific image.
  • name String - The display name for security group.
  • description String - The descripton name for a security group.
  • rules Array - The security group rules.
  • created_at String - A time value given in ISO8601 combined date and time format that represents when the image was created.
{
   "security_groups":[
      {
         "id":"string",
         "name":"string",
         "description":"string",
         "rules":[
            {
               "protocol":"icmp",
               "port_range_min":null,
               "port_range_max":null,
               "direction":"ingress"
            },
            {
               "protocol":"tcp",
               "port_range_min":22,
               "port_range_max":22,
               "direction":"ingress"
            },
            {
               "protocol":"tcp",
               "port_range_min":8080,
               "port_range_max":8085,
               "direction":"ingress"
            },
            {
               "protocol":"all",
               "port_range_min":null,
               "port_range_max":null,
               "direction":"egress"
            }
         ],
         "created_at":"2020-03-20T15:17:42.375Z"
      }
   ],
   "total_count":1,
   "page":1,
   "per_page":10
}

Get security group

Get details of an security group with the given ID

GET /compute/v1/security-group/{security_group_id} (HTTP 200 - OK)

Path parameters:

  • security_group_id String - Security group id

Response body

The response will be a JSON object that contains the security group attributes:

  • id String - A unique identifier that can be used to reference a specific image.
  • name String - The display name for security group.
  • description String - The descripton name for a security group.
  • rules Array - The security group rules.
  • created_at String - A time value given in ISO8601 combined date and time format that represents when the image was created.
{
   "security_group":{
      "id":"string",
      "name":"string",
      "description":"string",
      "rules":[
         {
            "protocol":"icmp",
            "port_range_min":null,
            "port_range_max":null,
            "direction":"ingress"
         },
         {
            "protocol":"tcp",
            "port_range_min":22,
            "port_range_max":22,
            "direction":"ingress"
         },
         {
            "protocol":"tcp",
            "port_range_min":8080,
            "port_range_max":8085,
            "direction":"ingress"
         },
         {
            "protocol":"all",
            "port_range_min":null,
            "port_range_max":null,
            "direction":"egress"
         }
      ],
      "created_at":"2020-03-20T15:17:42.375Z"
   }
}

Delete a security group

Delete a security group with the given ID

DELETE /compute/v1/security groups/<security_group_id>  (HTTP 204 - No content)

Path parameters:

  • security_group_id String - security group id

Examples (cURL)

# Create a new security group egress all ports
curl --request POST \
-H 'X-Auth-Token: <TOKEN>' -H 'Content-Type: application/json' \
'https://api.genesiscloud.com/compute/v1/security_groups' \
--data-raw '
{
   "name":"name",
   "description":"description",
   "rules":[
      {
         "protocol":"icmp",
         "port_range_min":null,
         "port_range_max":null,
         "direction":"ingress"
      },
      {
         "protocol":"tcp",
         "port_range_min":22,
         "port_range_max":22,
         "direction":"ingress"
      },
      {
         "protocol":"tcp",
         "port_range_min":8080,
         "port_range_max":8085,
         "direction":"ingress"
      },
      {
         "protocol":"all",
         "port_range_min":null,
         "port_range_max":null,
         "direction":"egress"
      }
   ]
}'
# Update a new security group
curl --request POST \
-H 'X-Auth-Token: <TOKEN>' -H 'Content-Type: application/json' \
'https://api.genesiscloud.com/compute/v1/security_groups' \
--data-raw '
{
   "name":"name",
   "description":"description",
   "rules":[
      {
         "protocol":"tcp",
         "port_range_min":8080,
         "port_range_max":8085,
         "direction":"ingress"
      },
      {
         "protocol":"all",
         "port_range_min":null,
         "port_range_max":null,
         "direction":"egress"
      }
   ]
}'
# List security groups
curl -H 'X-Auth-Token: <TOKEN>' -H 'Content-Type: application/json' \
'https://api.genesiscloud.com/compute/v1/security-groups'
# Get security group by id
curl -H 'X-Auth-Token: <TOKEN>' \
'https://api.genesiscloud.com/compute/v1/security-groups/<security_group_id>'
# Delete a security group by id
curl --request DELETE \
-H 'X-Auth-Token: <TOKEN>' \
'https://api.genesiscloud.com/compute/v1/security_group/<security_group_id>'