1 of 12

API How-Tos

Cloud API allows contract administrators, owners, and authenticated users with the required permissions to create a NSG and associate it with Network Interface Cards (NICs) or Virtual Machine (VM) resources.

Create a Default Network Security Group

Note: Only contract administrators, owners, and users with both permissions to the VDC concerned and createNetworkSecurityGroups privilege can create NSGs via API.

Prerequisite: You need an IONOS Cloud account with API credentials configured with the appropriate permissions.

You can create a Default NSG with predefined rules at the time of creation or during the update of a datacenter. You can use any of the following Cloud API requests with the property createDefaultSecurityGroup set to trueand the other required properties:

POST /datacenters/

PUT /datacenters/{datacenterId}

PATCH /datacenters/{datacenterId}

Request

curl --location 'https://api.ionos.com/cloudapi/v6/datacenters/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YYXabCDeFmLMO0c2hyYUBpb25vcy5jb206I1Bha2lzdGFuXzE=' \
--data '{
  "properties": {
    "name": "Production Datacenter",
    "description": "My Production Datacenter",
    "location": "us/las",
    "createDefaultSecurityGroup": true
  }
}'

Response

202 Accepted

{
 "id": "15f67991-0f51-4efc-a8ad-ef1fb31a480c",
 "type": "datacenter",
 "href": "<RESOURCE-URI>",
 "metadata": {
  "etag": "45480eb3fbfc31f1d916c1eaa4abdcc3",
  "createdDate": "2015-12-04T14:34:09.809Z",
  "createdBy": "user@example.com",
  "createdByUserId": "user@example.com",
  "lastModifiedDate": "2015-12-04T14:34:09.809Z",
  "lastModifiedBy": "user@example.com",
  "lastModifiedByUserId": "63cef532-26fe-4a64-a4e0-de7c8a506c90",
  "state": "AVAILABLE"
 },
 "properties": {
  "name": "Production datacenter",
  "description": "My Production Datacenter",
  "location": "us/las",
  "version": 8,
  "features": [
   "SSD"
  ],
  "secAuthProtection": true,
  "cpuArchitecture": [
   {
    "cpuFamily": "INTEL_ICELAKE",
    "maxCores": 62,
    "maxRam": 245760,
    "vendor": "AuthenticAMD"
   }
  ],
  "ipv6CidrBlock": "2001:db8:b06d:8f00::/56",
  "defaultSecurityGroupId": "15f67991-0f51-4efc-a8ad-ef1fb31a480c"
 }
}

Note: For CloudAPI, some resources are created asynchronously. You can check for the progress via the Status URL that is returned in the response header of the POST or PUT call.

Create a Custom Network Security Group

Note: Only contract administrators, owners, and users with both permissions to the VDC concerned and createNetworkSecurityGroups privilege can create NSGs via API.

Prerequisite: You need an IONOS Cloud account with API credentials configured with the appropriate permissions.

To create a Custom NSG, you need to use the following POST request providing the datacenterIdand the required properties:

POST /datacenters/{datacenterId}/securitygroups

Request

Response

202 Accepted

Note: For CloudAPI, some resources are created asynchronously. You can check for the progress via the Status URL that is returned in the response header of the POST or PUT call.

Convert a Custom Network Security Group to Default

Note: Only contract administrators, owners, and users with permissions to the VDC concerned can create and manage NSGs via API.

Prerequisite: You need an IONOS Cloud account with API credentials configured with the appropriate permissions.

You can convert a Custom NSG to a Default NSG during the update of a datacenter. You can use any of the following requests with the property defaultSecurityGroupId set to UUID of the NSG to be converted and the other required properties:

PUT /datacenters/{datacenterId}

PATCH /datacenters/{datacenterId}

Request

Response

202 Accepted

Note: For CloudAPI, some resources are created asynchronously. You can check for the progress via the Status URL that is returned in the response header of the POST or PUT call.

Retrieve Network Security Groups

Note: Only contract administrators, owners, and users with permissions to the VDC concerned can create and manage NSGs via API.

Prerequisite: You need an IONOS Cloud account with API credentials configured with the appropriate permissions.

To retrieve the NSGs, you need to use the following GET request using the datacenter ID:

GET /datacenters/{datacenterId}/securitygroups

Request

Response

200 OK

Retrieve Network Security Groups by Group ID

Note: Only contract administrators, owners, and users with permissions to the VDC concerned can create and manage NSGs via API.

Prerequisite: You need an IONOS Cloud account with API credentials configured with the appropriate permissions.

To retrieve the NSGs, you need to use the following GET request using the datacenter ID and securityGroupId:

GET /datacenters/{datacenterId}/securitygroups/{securityGroupId}

Request

Response

200 OK

Update a Network Security Group

Note: Only contract administrators, owners, and users with permissions to the VDC concerned can create and manage NSGs via API.

Prerequisite: You need an IONOS Cloud account with API credentials configured with the appropriate permissions.

To update a NSG, you need to use the following PUTor PATCH request providing the datacenterId, securityGroupIdand the required properties:

PUT(PATCH) /datacenters/{datacenterId}/securitygroups/{securityGroupId}

Request

Response

202 Accepted

Note: For CloudAPI, some resources are created asynchronously. You can check for the progress via the Status URL that is returned in the response header of the POST or PUT call.

Delete a Network Security Group

Note: Only contract administrators, owners, and users with permissions to the VDC concerned can create and manage NSGs via API.

Prerequisite: You need an IONOS Cloud account with API credentials configured with the appropriate permissions.

To delete a NSG, you need to use the following DELETE request providing the datacenterId and securityGroupId:

DELETE /datacenters/{datacenterId}/securitygroups/{securityGroupId}

Request

Response

202 Accepted

Create Firewall rule for a Network Security Group

Note: Only contract administrators, owners, and users with permissions to the VDC concerned can create and manage NSGs via API.

Prerequisite: You need an IONOS Cloud account with API credentials configured with the appropriate permissions.

To create a firewall rule for a NSG, you need to use the following POST request providing the datacenterId and securityGroupId:

POST /datacenters/{datacenterId}/securitygroups/{securityGroupId}/rules

Request

Response

202 Accepted

Note: For CloudAPI, some resources are created asynchronously. You can check for the progress via the Status URL that is returned in the response header of the POST or PUT call.

Retrieve Firewall rules by Network Security Group ID

Note: Only contract administrators, owners, and users with permissions to the VDC concerned can create and manage NSGs via API.

Prerequisite: You need an IONOS Cloud account with API credentials configured with the appropriate permissions.

To retrieve the firewall rules by Network Security Group ID, you need to use one of the following Cloud APIGET request using the datacenterId and securityGroupId:

GET /datacenters/{datacenterId}/securitygroups/{securityGroupId}/rules

GET /datacenters/{datacenterId}/securitygroups/{securityGroupId}/rules/{ruleId}

Request

curl --location 'https://api.ionos.com/cloudapi/v6/datacenters/5a88aa8b-8aa1-51f6-XXd1-XXXXXe9f31/securitygroups/b0a54xyz-abcd-8008-8883-XX0e0428e888/rules' \
--header 'Authorization: Basic YYXabCDeFmLMO0c2hyYUBpb25vcy5jb206I1Bha2lzdGFuXzE='

Response

200 OK

{
    "id": "b0a54xyz-abcd-8008-8883-XX0e0428e888/rules",
    "type": "collection",
    "href": "https://api.ionos.com/cloudapi/v6/datacenters/5a88aa8b-8aa1-51f6-XXd1-XXXXXe9f31/securitygroups/b0a54xyz-abcd-8008-8883-XX0e0428e888/rules",
    "items": [
        {
            "id": "0A0X0885-88ix-8xxX-1020-888a4f0f8137",
            "type": "firewall-rule",
            "href": "https://api.ionos.com/cloudapi/v6/datacenters/5a88aa8b-8aa1-51f6-XXd1-XXXXXe9f31/securitygroups/b0a54xyz-abcd-8008-8883-XX0e0428e888/rules/0A0X0885-88ix-8xxX-1020-888a4f0f8137"
        }
    ]
}

Delete Firewall rule from a Network Security Group

Note: Only contract administrators, owners, and users with permissions to the VDC concerned can create and manage NSGs via API.

Prerequisite: You need an IONOS Cloud account with API credentials configured with the appropriate permissions.

To delete a firewall rule from a NSG, you need to use the following Cloud API DELETE request providing the datacenterId, securityGroupId and ruleId:

DELETE /datacenters/{datacenterId}/securitygroups/{securityGroupId}/rules/{ruleId}

Request

curl --location --request DELETE 'https://api.ionos.com/cloudapi/v6/datacenters/5a88aa8b-8aa1-51f6-XXd1-XXXXXe9f31/securitygroups/bxxxx-axXX-0008-8888-99k0444e5555/rules/axxxx-axXX-0008-8888-99k0444e5555' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YYXabCDeFmLMO0c2hyYUBpb25vcy5jb206I1Bha2lzdGFuXzE=' \

Response

202 Accepted

Attach a List of Security Groups to a Server or NIC

Note: Updating the list of Security Groups attached to an existing server specified by its ID. Security Groups should already exist as part of the datacenter.

Note: Only contract administrators, owners, and users with permissions to the VDC concerned can create and manage NSGs via API.

Prerequisite: You need an IONOS Cloud account with API credentials configured with the appropriate permissions.

To attach a list of NSGs to a server, you need to use the following Cloud API PUT request providing the datacenterId,serverId and the IDs of the security groups in the body:

PUT /datacenters/{datacenterId}/servers/{serverId}/securitygroups

Similarly for a NIC, provide the datacenterId, nicId and the IDs of the security groups in the body:

PUT /datacenters/{datacenterId}/servers/{serverId}/nic/{nicId}/securitygroups

Request

curl --location --request PUT 'https://api.ionos.com/cloudapi/v6/datacenters/5a88aa8b-8aa1-51f6-XXd1-XXXXXe9f31/servers/bxxxx-axXX-0008-8888-99k0444e5555/securitygroups' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YYXabCDeFmLMO0c2hyYUBpb25vcy5jb206I1Bha2lzdGFuXzE=' \
--data '{
  "ids": [
    "ac51b8e4-050c-4941-b7cd-43923422fe6e",
    "ea737d87-8754-4a42-b97c-0b1a8f619de5"
  ]
}'

Response

200 Accepted

{
  "id": "15f67991-0f51-4efc-a8ad-ef1fb31a480c",
  "type": "collection",
  "href": "<RESOURCE-URI>",
  "items": [
    "string"
  ],
  "offset": 0,
  "limit": 1000,
  "_links": {
    "prev": "<PREVIOUS-PAGE-URI>",
    "self": "<THIS-PAGE-URI>",
    "next": "<NEXT-PAGE-URI>"
  }
}