Security groups operations#

This section describes the API operations for security groups. For general information about security groups and security group rules, see Security groups concepts.

List security groups#

GET /v2.0/security-groups

This operation retrieves a list of all security groups to which the specified tenant has access.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	Success	Request succeeded.
401	Unauthorized	The user is unauthorized to make this request.

Request#

This operation does not accept a request body.

Response#

This table shows the body parameters for the response:

Name	Type	Description
security_groups	Array	The array of security group details.
security_groups.id	Uuid	The UUID for the security group.
security_groups.name	String	The security group name.
security_groups.description	String	The security group description.
security_groups.tenant_id	Uuid	The tenant ID of the security group owner.
security_groups.security_group_rules	String	An array of rules in a security group.
security_groups.security_group_rules.id	Uuid	The ID for the security group rule.
security_groups.security_group_rules.direction	String	The direction of traffic. An `ingress` rule applies to incoming server traffic and an `egress` rule applies to outgoing server traffic.
security_groups.security_group_rules.ethertype	String	The network ether type, either `IPv4` or `IPv6`.
security_groups.security_group_rules.security_group_id	Uuid	The security group ID for the security group with which the rule is associated.
security_groups.security_group_rules.tenant_id	Uuid	The tenant ID of the security group rule owner.
security_groups.security_group_rules.port_range_min	Int	The minimum port number in the range that is matched by the security group rule. If the protocol is `TCP` or `UDP`, this value must be less than or equal to the value of the `port_range_max` parameter. If the protocol is `ICMP`, this value may be an `ICMP` type. If the protocol attribute is “null”, this value must be “null”.
security_groups.security_group_rules.port_range_max	Int	The maximum port number in the range that is matched by the security group rule. The `port_range_min` parameter constrains this `port_range_max` parameter. If the protocol is `ICMP`, this value may be an `ICMP` code. If the protocol attribute is “null”, this value must be “null”.
security_groups.security_group_rules.protocol	String	The protocol. Set to null.
security_groups.security_group_rules.remote_group_id	String	The remote group ID. This attribute must be set to null since self- referential Security Groups are not supported.
security_groups.security_group_rules.remote_ip_prefix	String	The remote IP prefix. This attribute matches the specified IP prefix as the source IP address of the IP packet.

Example List security groups: JSON response

{
    "security_groups": [
        {
            "description": "default",
            "id": "85cc3048-abc3-43cc-89b3-377341426ac5",
            "name": "default",
            "security_group_rules": [
                {
                    "direction": "ingress",
                    "ethertype": "IPv6",
                    "id": "c0b09f00-1d49-4e64-a0a7-8a186d928138",
                    "port_range_max": 22,
                    "port_range_min": 22,
                    "protocol": "TCP",
                    "remote_group_id": null,
                    "remote_ip_prefix": null,
                    "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                    "tenant_id": "5831008"
                },
                {
                    "direction": "ingress",
                    "ethertype": "IPv4",
                    "id": "f7d45c89-008e-4bab-88ad-d6811724c51c",
                    "port_range_max": 22,
                    "port_range_min": 22,
                    "protocol": "TCP",
                    "remote_group_id": null,
                    "remote_ip_prefix": null,
                    "security_group_id": "85cc3048-abc3-43cc-89b3-377341426ac5",
                    "tenant_id": "5831008"
                }
            ],
            "tenant_id": "5831008"
        }
    ]
}

Create security group#

POST /v2.0/security-groups

This operation creates a security group with default security group rules for the IPv4 and IPv6 ether types.

This table shows the possible response codes for this operation:

Response Code	Name	Description
201	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	The user is unauthorized to make this request.

Request#

This table shows the body parameters for the request:

Name	Type	Description
security_group	Object	A container for security group details.
security_group.name	String	A symbolic name for the security group, which does not need to be unique.
security_group.description	String (Optional)	Describes the security group.

Example Create security group: JSON request

{
   "security_group":{
      "name":"new-webservers",
      "description":"security group for webservers"
   }
}

Response#

This table shows the body parameters for the response:

Name	Type	Description
security_group	Object	The container for security group details.
security_group.id	Uuid	The UUID for the security group.
security_group.name	String	The security group name.
security_group.description	String	The security group description.
security_group.tenant_id	Uuid	The tenant ID of the security group owner.
security_group.security_group_rules	String	An array of rules in a security group.
security_group.security_group_rules.id	Uuid	The ID for the security group rule.
security_group.security_group_rules.direction	String	The direction of traffic. An `ingress` rule applies to incoming server traffic and an `egress` rule applies to outgoing server traffic.
security_group.security_group_rules.ethertype	String	The network ether type, either `IPv4` or `IPv6`.
security_group.security_group_rules.security_group_id	Uuid	The security group ID for the security group with which the rule is associated.
security_group.security_group_rules.tenant_id	Uuid	The tenant ID of the security group rule owner.
security_group.security_group_rules.port_range_min	Int	The minimum port number in the range that is matched by the security group rule. If the protocol is `TCP` or `UDP`, this value must be less than or equal to the value of the `port_range_max` parameter. If the protocol is `ICMP`, this value may be an `ICMP` type. If the protocol attribute is “null”, this value must be “null”.
security_group.security_group_rules.port_range_max	Int	The maximum port number in the range that is matched by the security group rule. The `port_range_min` parameter constrains this `port_range_max` parameter. If the protocol is `ICMP`, this value may be an `ICMP` code. If the protocol attribute is “null”, this value must be “null”.
security_group.security_group_rules.protocol	String	The protocol. Set to null.
security_group.security_group_rules.remote_group_id	String	The remote group ID. This attribute must be set to null since self- referential Security Groups are not supported.
security_group.security_group_rules.remote_ip_prefix	String	The remote IP prefix. This attribute matches the specified IP prefix as the source IP address of the IP packet.

Example Create security group: JSON response

{
   "security_group":{
      "description":"security group for webservers",
      "id":"10fb1612-f78f-4d35-b008-15133520debe",
      "name":"new-webservers",
      "security_group_rules":[],
      "tenant_id":"5831008"
   }
}

Show security group#

GET /v2.0/security-groups/{security_group_id}

This operation returns a response body that contains the description, name, security group ID, tenant ID, and security group rules associated with the specified security group.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	Success	Request succeeded.
401	Unauthorized	The user is unauthorized to make this request.
404	Not Found	Item not found.

Request#

This table shows the URI parameters for the request:

Name	Type	Description
{security_group_id}	Uuid	The unique identifier of the security group.

This operation does not accept a request body.

Response#

This table shows the body parameters for the response:

Name	Type	Description
security_group	Object	The container for security group details.
security_group.id	Uuid	The UUID for the security group.
security_group.name	String	The security group name.
security_group.description	String	The security group description.
security_group.tenant_id	Uuid	The tenant ID of the security group owner.
security_group.security_group_rules	String	An array of rules in a security group.
security_group.security_group_rules.id	Uuid	The ID for the security group rule.
security_group.security_group_rules.direction	String	The direction of traffic. An `ingress` rule applies to incoming server traffic and an `egress` rule applies to outgoing server traffic.
security_group.security_group_rules.ethertype	String	The network ether type, either `IPv4` or `IPv6`.
security_group.security_group_rules.security_group_id	Uuid	The security group ID for the security group with which the rule is associated.
security_group.security_group_rules.tenant_id	Uuid	The tenant ID of the security group rule owner.
security_group.security_group_rules.port_range_min	Int	The minimum port number in the range that is matched by the security group rule. If the protocol is `TCP` or `UDP`, this value must be less than or equal to the value of the `port_range_max` parameter. If the protocol is `ICMP`, this value may be an `ICMP` type. If the protocol attribute is “null”, this value must be “null”.
security_group.security_group_rules.port_range_max	Int	The maximum port number in the range that is matched by the security group rule. The `port_range_min` parameter constrains this `port_range_max` parameter. If the protocol is `ICMP`, this value may be an `ICMP` code. If the protocol attribute is “null”, this value must be “null”.
security_group.security_group_rules.protocol	String	The protocol. Set to null.
security_group.security_group_rules.remote_group_id	String	The remote group ID. This attribute must be set to null since self- referential Security Groups are not supported.
security_group.security_group_rules.remote_ip_prefix	String	The remote IP prefix. This attribute matches the specified IP prefix as the source IP address of the IP packet.

Example Show security group: JSON response

{
   "security_group":{
      "description":"default",
      "id":"85cc3048-abc3-43cc-89b3-377341426ac5",
      "name":"default",
      "security_group_rules":[
         {
            "direction":"ingress",
            "ethertype":"IPv6",
            "id":"c0b09f00-1d49-4e64-a0a7-8a186d928138",
            "port_range_max":22,
            "port_range_min":22,
            "protocol":"TCP",
            "remote_group_id":null,
            "remote_ip_prefix":null,
            "security_group_id":"85cc3048-abc3-43cc-89b3-377341426ac5",
            "tenant_id":"5831008"
         },
         {
            "direction":"ingress",
            "ethertype":"IPv4",
            "id":"f7d45c89-008e-4bab-88ad-d6811724c51c",
            "port_range_max":22,
            "port_range_min":22,
            "protocol":"TCP",
            "remote_group_id":null,
            "remote_ip_prefix":null,
            "security_group_id":"85cc3048-abc3-43cc-89b3-377341426ac5",
            "tenant_id":"5831008"
         }
      ],
      "tenant_id":"5831008"
   }
}

Delete security group#

DELETE /v2.0/security-groups/{security_group_id}

This operation deletes a security group and its associated security group rules. The delete operation fails if a port is associated with the security group.

This table shows the possible response codes for this operation:

Response Code	Name	Description
204	Success	Request succeeded.
401	Unauthorized	The user is unauthorized to make this request.
404	Not Found	Item not found.

Request#

This table shows the URI parameters for the request:

Name	Type	Description
{security_group_id}	Uuid	The unique identifier of the security group.

This operation does not accept a request body.

Response#

Example Delete security group: JSON response

Content-Type: application/json
Accept: application/json
status: 204

List security group rules#

GET /v2.0/security-group-rules

This operation retrieves a list of security group rules for the requester with the unique ID for each security group rule.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	Success	Request succeeded.
401	Unauthorized	The user is unauthorized to make this request.

Request#

This operation does not accept a request body.

Response#

This table shows the body parameters for the response:

Name	Type	Description
security_group_rules	Array	An array for the security group rules.
security_group_rules.direction	String	The direction of traffic. An `ingress` rule is applied to incoming server traffic and an `egress` rule is applied to outgoing server traffic.
security_group_rules.ethertype	String	The network ether type, either `IPv4` or `IPv6`. Addresses represented in CIDR must match the ingress rules.
security_group_rules.security_group_id	Uuid	The ID of the security group to associate with this security group rule.
security_group_rules.port_range_min	Int	The minimum port number in the range that is matched by the security group rule. If the protocol is `TCP` or `UDP`, this value must be less than or equal to the value of the `port_range_max` parameter. If the protocol is `ICMP`, this value may be an `ICMP` type. If the protocol attribute is “null”, this value must be “null”.
security_group_rules.port_range_max	Int	The maximum port number in the range that is matched by the security group rule. The `port_range_min` parameter constrains this `port_range_max` parameter. If the protocol is `ICMP`, this value may be an `ICMP` code. If the protocol attribute is “null”, this value must be “null”.
security_group_rules.protocol	String	The protocol that is matched by the security group rule. Valid values are `null`, `tcp`, `udp`, and `icmp`.
security_group_rules.remote_group_id	Uuid	The remote group ID to be associated with this security group rule. This attribute must be set to null since self-referential Security Groups are not supported.
security_group_rules.remote_ip_prefix	Uuid	The remote IP prefix to be associated with this security group rule. This attribute matches the specified IP prefix as the source IP address of the IP packet.

Example List security group rules: JSON response

{
   "security_group_rules":[
      {
         "direction":"ingress",
         "ethertype":"IPv6",
         "id":"c0b09f00-1d49-4e64-a0a7-8a186d928138",
         "port_range_max":22,
         "port_range_min":22,
         "protocol":"TCP",
         "remote_group_id":null,
         "remote_ip_prefix":null,
         "security_group_id":"85cc3048-abc3-43cc-89b3-377341426ac5",
         "tenant_id":"5831008"
      },
      {
         "direction":"ingress",
         "ethertype":"IPv4",
         "id":"f7d45c89-008e-4bab-88ad-d6811724c51c",
         "port_range_max":22,
         "port_range_min":22,
         "protocol":"TCP",
         "remote_group_id":null,
         "remote_ip_prefix":null,
         "security_group_id":"85cc3048-abc3-43cc-89b3-377341426ac5",
         "tenant_id":"5831008"
      }
   ]
}

Create security group rule#

POST /v2.0/security-group-rules

This operation creates a security group rule.

This table shows the possible response codes for this operation:

Response Code	Name	Description
201	Success	Request succeeded.
400	Error	A general error has occured.
401	Unauthorized	The user is unauthorized to make this request.
404	Not Found	Item not found.
409	buildInProgress	Build is in progress.

Request#

This table shows the body parameters for the request:

Name	Type	Description
security_group_rule	String	An object to contain the security group rules.
security_group_rule.direction	String	The direction of traffic. An `ingress` rule is applied to incoming server traffic and an `egress` rule is applied to outgoing server traffic.
security_group_rule.ethertype	String	The network ether type, either `IPv4` or `IPv6`. Addresses represented in CIDR must match the ingress rules.
security_group_rule.security_group_id	Uuid	The ID of the security group to associate with this security group rule.
security_group_rule.port_range_min	Int	The minimum port number in the range that is matched by the security group rule. If the protocol is `TCP` or `UDP`, this value must be less than or equal to the value of the `port_range_max` parameter. If the protocol is `ICMP`, this value may be an `ICMP` type. If the protocol attribute is “null”, this value must be “null”.
security_group_rule.port_range_max	Int	The maximum port number in the range that is matched by the security group rule. The `port_range_min` parameter constrains this `port_range_max` parameter. If the protocol is `ICMP`, this value may be an `ICMP` code. If the protocol attribute is “null”, this value must be “null”.
security_group_rule.protocol	String	The protocol that is matched by the security group rule. Valid values are `null`, `tcp`, `udp`, and `icmp`.
security_group_rule.remote_group_id	Uuid	The remote group ID to be associated with this security group rule. This attribute must be set to null since self-referential Security Groups are not supported.
security_group_rule.remote_ip_prefix	Uuid	The remote IP prefix to be associated with this security group rule. This attribute matches the specified IP prefix as the source IP address of the IP packet.

Example Create security group rule: JSON request

POST /v2.0/security-group-rules.json
Accept: application/json
{
   "security_group_rule":{
      "direction":"ingress",
      "port_range_min":"80",
      "ethertype":"IPv4",
      "port_range_max":"80",
      "protocol":"TCP",
      "remote_group_id":null,
      "security_group_id":"a7734e61-b545-452d-a3cd-0189cbd9747a"
   }
}

Response#

This table shows the body parameters for the response:

Name	Type	Description
security_group_rule	String	An array of rules in a security group.
security_group_rule.id	Uuid	The ID for the security group rule.
security_group_rule.direction	String	The direction of traffic. An `ingress` rule is applied to incoming server traffic and an `egress` rule is applied to outgoing server traffic.
security_group_rule.ethertype	String	The network ether type, either `IPv4` or `IPv6`.
security_group_rule.security_group_id	Uuid	The security group ID for the security group with which the rule is associated.
security_group_rule.tenant_id	Uuid	The tenant ID of the security group rule owner.
security_group_rule.port_range_min	Int	The minimum port number in the range that is matched by the security group rule. If the protocol is `TCP` or `UDP`, this value must be less than or equal to the value of the `port_range_max` parameter. If the protocol is `ICMP`, this value may be an `ICMP` type. If the protocol attribute is “null”, this value must be “null”.
security_group_rule.port_range_max	Int	The maximum port number in the range that is matched by the security group rule. The `port_range_min` parameter constrains this `port_range_max` parameter. If the protocol is `ICMP`, this value may be an `ICMP` code. If the protocol attribute is “null”, this value must be “null”.
security_group_rule.protocol	String	The protocol. Set to null.
security_group_rule.remote_group_id	String	The remote group ID. This attribute must be set to null since self-referential Security Groups are not supported.
security_group_rule.remote_ip_prefix	String	The remote IP prefix. This attribute matches the specified IP prefix as the source IP address of the IP packet.

Example Create security group rule: JSON response

{
   "security_group_rule":{
      "direction":"ingress",
      "ethertype":"IPv4",
      "id":"2bc0accf-312e-429a-956e-e4407625eb62",
      "port_range_max":80,
      "port_range_min":80,
      "protocol":"TCP",
      "remote_group_id":null,
      "remote_ip_prefix":null,
      "security_group_id":"a7734e61-b545-452d-a3cd-0189cbd9747a",
      "tenant_id":"5831008"
   }
}

Show security group rule#

GET /v2.0/security-group-rules/{rules-security-groups-id}

This operation retrieves information about the specified security group rule.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	Success	Request succeeded.
401	Unauthorized	The user is unauthorized to make this request.
404	Not Found	Item not found.

Request#

This table shows the URI parameters for the request:

Name	Type	Description
{rules-security-groups-id}	Uuid	The unique identifier of the security group rule.

This operation does not accept a request body.

Response#

This table shows the body parameters for the response:

Name	Type	Description
security_group_rule	String	An object to contain the security group rules.
security_group_rule.direction	String	The direction of traffic. An `ingress` rule is applied to incoming server traffic and an `egress` rule is applied to outgoing server traffic.
security_group_rule.ethertype	String	The network ether type, either `IPv4` or `IPv6`. Addresses represented in CIDR must match the ingress rules.
security_group_rule.security_group_id	Uuid	The ID of the security group to associate with this security group rule.
security_group_rule.port_range_min	Int	The minimum port number in the range that is matched by the security group rule. If the protocol is `TCP` or `UDP`, this value must be less than or equal to the value of the `port_range_max` parameter. If the protocol is `ICMP`, this value may be an `ICMP` type. If the protocol attribute is “null”, this value must be “null”.
security_group_rule.port_range_max	Int	The maximum port number in the range that is matched by the security group rule. The `port_range_min` parameter constrains this `port_range_max` parameter. If the protocol is `ICMP`, this value may be an `ICMP` code. If the protocol attribute is “null”, this value must be “null”.
security_group_rule.protocol	String	The protocol that is matched by the security group rule. Valid values are `null`, `tcp`, `udp`, and `icmp`.
security_group_rule.remote_group_id	Uuid	The remote group ID to be associated with this security group rule. This attribute must be set to null since self-referential Security Groups are not supported.
security_group_rule.remote_ip_prefix	Uuid	The remote IP prefix to be associated with this security group rule. This attribute matches the specified IP prefix as the source IP address of the IP packet.

Example Show security group rule: JSON response

{
   "security_group_rule":{
      "direction":"ingress",
      "ethertype":"IPv6",
      "id":"c0b09f00-1d49-4e64-a0a7-8a186d928138",
      "port_range_max":22,
      "port_range_min":22,
      "protocol":"TCP",
      "remote_group_id":null,
      "remote_ip_prefix":null,
      "security_group_id":"85cc3048-abc3-43cc-89b3-377341426ac5",
      "tenant_id":"5831008"
   }
}

Delete security group rule#

DELETE /v2.0/security-group-rules/{rules-security-groups-id}

This operation deletes the specified rule from a security group.

This table shows the possible response codes for this operation:

Response Code	Name	Description
204	Success	Request succeeded.
401	Unauthorized	The user is unauthorized to make this request.
404	Not Found	Item not found.

Request#

This table shows the URI parameters for the request:

Name	Type	Description
{rules-security-groups-id}	Uuid	The unique identifier of the security group rule.

This operation does not accept a request body.

Response#

Example Delete security group rule: JSON response

Content-Type: application/json
Accept: application/json
status: 204