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 Cloud API POST request providing the datacenterIdand the required properties:

POST /datacenters/{datacenterId}/securitygroups

Request

curl --location 'https://api.ionos.com/cloudapi/v6/datacenters/5a88aa8b-8aa1-51f6-XXd1-XXXXXe9f31/securitygroups' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YYXabCDeFmLMO0c2hyYUBpb25vcy5jb206I1Bha2lzdGFuXzE=' \
--data '{
    "properties": {
        "name": "NSG-1",
        "description": "Description for NSG-1"
    }
}'

Response

202 Accepted

{
    "id": "bxxxx-axXX-0008-8888-99k0444e5555",
    "type": "security-group",
    "href": "https://api.ionos.com/cloudapi/v6/datacenters/5a88aa8b-8aa1-51f6-XXd1-XXXXXe9f31/securitygroups/bxxxx-axXX-0008-8888-99k0444e5555",
    "metadata": {
        "etag": "64c593ebd78b0d9da52baba4079e119d",
        "createdDate": "2024-05-17T15:11:09Z",
        "createdBy": "test.test@ionos.com",
        "createdByUserId": "XYaf0375-1c1d-4387-9ef1-6ee95d30e54a",
        "lastModifiedDate": "2024-05-17T15:11:09Z",
        "lastModifiedBy": "test.test@ionos.com",
        "lastModifiedByUserId": "XYaf0375-1c1d-4387-9ef1-6ee95d30e54a",
        "state": "BUSY"
    },
    "properties": {
        "name": "NSG-1",
        "description": "Description for NSG-1"
    }
}

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 Cloud API 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

curl --location 'https://api.ionos.com/cloudapi/v6/datacenters/15f67991-0f51-4efc-a8ad-ef1fb31a480c' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YYXabCDeFmLMO0c2hyYUBpb25vcy5jb206I1Bha2lzdGFuXzE=' \
--data '{
  "properties": {
    "name": "Production Datacenter",
    "description": "My Production Datacenter",
    "location": "us/las",
    "defaultSecurityGroupId": "15f67991-0f51-4efc-a8ad-ef1fb31a480c"
  }
}'

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.

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 Cloud APIGET request using the datacenter ID:

GET /datacenters/{datacenterId}/securitygroups

Request

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

Response

200 OK

{
    "id": "5a88aa8b-8aa1-51f6-XXd1-XXXXXe9f31/securitygroups",
    "type": "collection",
    "href": "https://api.ionos.com/cloudapi/v6/datacenters/5a88aa8b-8aa1-51f6-XXd1-XXXXXe9f31/securitygroups",
    "items": [
        {
            "id": "bxxxx-axXX-0008-8888-99k0444e5555",
            "type": "security-group",
            "href": "https://api.ionos.com/cloudapi/v6/datacenters/5a88aa8b-8aa1-51f6-XXd1-XXXXXe9f31/securitygroups/bxxxx-axXX-0008-8888-99k0444e5555"
        }
    ]
}

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 Cloud APIGET request using the datacenter ID and securityGroupId:

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

Request

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

Response

200 OK

{
    "id": "b0a54xyz-abcd-8008-8883-XX0e0428e888",
    "type": "security-group",
    "href": "https://api.ionos.com/cloudapi/v6/datacenters/5a88aa8b-8aa1-51f6-XXd1-XXXXXe9f31/securitygroups/b0a54xyz-abcd-8008-8883-XX0e0428e888",
    "metadata": {
        "etag": "3a6a61187c03e11a41769e60a0610b54",
        "createdDate": "2024-05-17T15:11:11Z",
        "createdBy": "test.test@ionos.com",
        "createdByUserId": "XYaf0375-1c1d-4387-9ef1-6ee95d30e54a",
        "lastModifiedDate": "2024-05-17T15:11:11Z",
        "lastModifiedBy": "test.test@ionos.com",
        "lastModifiedByUserId": "XYaf0375-1c1d-4387-9ef1-6ee95d30e54a",
        "state": "AVAILABLE"
    },
    "properties": {
        "name": "My FWR",
        "description": null
    },
    "entities": {
        "rules": {
            "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"
        },
        "servers": {
            "id": "b0a54xyz-abcd-8008-8883-XX0e0428e888/servers",
            "type": "collection",
            "href": "https://api.ionos.com/cloudapi/v6/datacenters/5a88aa8b-8aa1-51f6-XXd1-XXXXXe9f31/securitygroups/b0a54xyz-abcd-8008-8883-XX0e0428e888/servers"
        },
        "nics": {
            "id": "b0a54xyz-abcd-8008-8883-XX0e0428e888/nics",
            "type": "collection",
            "href": "https://api.ionos.com/cloudapi/v6/datacenters/5a88aa8b-8aa1-51f6-XXd1-XXXXXe9f31/securitygroups/b0a54xyz-abcd-8008-8883-XX0e0428e888/nics"
        }
    }
}

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 Cloud API PUTor PATCH request providing the datacenterId, securityGroupIdand the required properties:

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

Request

curl --location --request PUT 'https://api.ionos.com/cloudapi/v6/datacenters/5a88aa8b-8aa1-51f6-XXd1-XXXXXe9f31/securitygroups/b3f55c2d-a89e-4008-8213-92e0428e2555' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YYXabCDeFmLMO0c2hyYUBpb25vcy5jb206I1Bha2lzdGFuXzE=' \
--data '{
    "properties": {
        "name": "NSG",
        "description": "updated to true"
    }

}'

Response

202 Accepted

{
    "id": "bxxxx-axXX-0008-8888-99k0444e5555",
    "type": "security-group",
    "href": "https://api.ionos.com/cloudapi/v6/datacenters/5a88aa8b-8aa1-51f6-XXd1-XXXXXe9f31/securitygroups/bxxxx-axXX-0008-8888-99k0444e5555",
    "metadata": {
        "etag": "e15475860e9c6e1136ba1b2153297f31",
        "createdDate": "2024-05-17T15:11:11Z",
        "createdBy": "test.test@ionos.com",
        "createdByUserId": "a5af0375-1c1d-4387-9ef1-6ee95d30e54a",
        "lastModifiedDate": "2024-05-21T18:02:41Z",
        "lastModifiedBy": "test.test@ionos.com",
        "lastModifiedByUserId": "a5af0375-1c1d-4387-9ef1-6ee95d30e54a",
        "state": "BUSY"
    },
    "properties": {
        "name": "NSG",
        "description": "updated to true"
    },
    "entities": {
        "rules": {
            "id": "b3f55c2d-a89e-4008-8213-92e0428e2555/rules",
            "type": "collection",
            "href": "https://api.ionos.com/cloudapi/v6/datacenters/5a88aa8b-8aa1-51f6-XXd1-XXXXXe9f31/securitygroups/bxxxx-axXX-0008-8888-99k0444e5555/rules"
        },
        "servers": {
            "id": "b3f55c2d-a89e-4008-8213-92e0428e2555/servers",
            "type": "collection",
            "href": "https://api.ionos.com/cloudapi/v6/datacenters/5a88aa8b-8aa1-51f6-XXd1-XXXXXe9f31/securitygroups/bxxxx-axXX-0008-8888-99k0444e5555/servers"
        },
        "nics": {
            "id": "b3f55c2d-a89e-4008-8213-92e0428e2555/nics",
            "type": "collection",
            "href": "https://api.ionos.com/cloudapi/v6/datacenters/5a88aa8b-8aa1-51f6-XXd1-XXXXXe9f31/securitygroups/bxxxx-axXX-0008-8888-99k0444e5555/nics"
        }
    }
}

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 Cloud API DELETE request providing the datacenterId and securityGroupId:

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

Request

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

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 Cloud API POST request providing the datacenterId and securityGroupId:

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

Request

curl --location 'https://api.ionos.com/cloudapi/v6/datacenters/5a88aa8b-8aa1-51f6-XXd1-XXXXXe9f31/securitygroups/bxxxx-axXX-0008-8888-99k0444e5555/rules' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YYXabCDeFmLMO0c2hyYUBpb25vcy5jb206I1Bha2lzdGFuXzE=' \
--data '{
    "properties":{
        "name": "My FWR",
        "protocol": "TCP",
        "sourceMac": "00:0a:95:9d:68:16",
        "ipVersion": "IPv4",
        "sourceIp": "22.231.113.12",
        "targetIp": "22.231.113.64",
        "portRangeStart": 8,
        "portRangeEnd": 8,
        "type": "INGRESS"
        }
}'

Response

202 Accepted

{
    "id": "0XX070155-XXaf-XXbb-XX20-088x8f0f8137",
    "type": "firewall-rule",
    "href": "https://api.ionos.com/cloudapi/v6/datacenters/5a88aa8b-8aa1-51f6-XXd1-XXXXXe9f31/securitygroups/bxxxx-axXX-0008-8888-99k0444e5555/rules/0d070155-85af-4abb-9120-058c4f0f8137",
    "metadata": {
        "etag": "aca11533be9480b3df9324a7976dd42a",
        "createdDate": "2024-05-21T14:20:32Z",
        "createdBy": "test.test@ionos.com",
        "createdByUserId": "a5af0375-1c1d-4387-9ef1-6ee95d30e54a",
        "lastModifiedDate": "2024-05-21T14:20:32Z",
        "lastModifiedBy": "test.test@ionos.com",
        "lastModifiedByUserId": "a5af0375-1c1d-4387-9ef1-6ee95d30e54a",
        "state": "BUSY"
    },
    "properties": {
        "name": "My FWR",
        "protocol": "TCP",
        "sourceMac": "00:0a:95:9d:68:16",
        "sourceIp": "22.231.113.12",
        "targetIp": "22.231.113.64",
        "icmpCode": null,
        "icmpType": null,
        "portRangeStart": 8,
        "portRangeEnd": 8,
        "ipVersion": "IPv4",
        "type": "INGRESS"
    }
}

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 GET request using the datacenterId and securityGroupId:

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

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

Request

Response

200 OK

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 DELETE request providing the datacenterId, securityGroupId and ruleId:

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

Request

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>"
  }
}