Get Started with IONOS API

Learn how to use IONOS API and begin integrating them to leverage the capabilities of IONOS services through this guide.

Base URL

Provide the Base URL of the IONOS API. Example: https://api.ionos.com/

Authorization

To log in to the IONOS API, you need to use either of the following authentication methods:

Note:

• All user accounts with currently 2FA enabled or forced need to use the Bearer Token Authentication method.

• The Basic Authentication method will be discontinued in the near future and it should be used in combination with 2FA to increase security.

• For the Reseller accounts, the Bearer Token Authentication improves handling as the additional header token for sub-contracts is not be required.

Basic Authentication

To authenticate using a Basic Authentication with the IONOS API, follow these steps:

1. Request a token using the following GET command:

       {{BaseURL}}/auth/v1/tokens/generate

2. You need to pass the encoded Base64 token in your CURL command. You can obtain the Encoded Base64 format and generate the token by using:

   • Username

   • Password

3. Once you receive the Base64 encoded token, you can use it in your cURL command to obtain the Basic Authentication token:

   curl --location \
   --request GET 'https://api.ionos.com/auth/v1/tokens/generate' \
   --header 'Authorization: Basic WVhKemFHRmtMbUoxYzJoeVlVQnBiMjV2Y3k1amIyMDZJMUJoYTJsemRHRnVYekU9' \
   --data ''

4. If your request is successful, the response will include an access token. This token is a string of characters that serves as your authentication credential for subsequent API requests. Retrieve the access token to interact with the APIs.

Bearer Token Authentication

To authenticate using a Bearer Token with the IONOS API, follow these steps:

1. Request a token using the following GET command:

    {{BaseURL}}/auth/v1/tokens/generate

1. You need to pass the secure token in your cURL command. You can obtain the secure token by using:

2. Generate authentication token via DCD

3. Generate authentication token via API

4. Generate authentication token via CLI

5. Once you receive the secure token, you can use the access token in your cURL command to obtain the Bearer Token:

curl --location \
--request GET 'https://api.ionos.com/auth/v1/tokens/generate'
--header 'Authorization: Bearer eyJpZCI6MTUsInVzZXJuYW1lIjoia21pbmNoZWxsZSIsImVtYWlsIjoia21pbmNoZWxsZUBxcS5jb20iLCJmaXJzdE5hbWUiOiJKZWFubmUiLCJsYXN0TmFtZSI6IkhhbHZvcnNvbiIsImdlbmRlciI6ImZlbWFsZSIsImltYWdlIjoiaHR0cHM6Ly9yb2JvaGFzaC5vcmcvYXV0cXVpYXV0LnBuZz9zaXplPTUweDUwJnNldD1zZXQxIiwiaWF0IjoxNjM1NzczOTYyLCJleHAiOjE2MzU3Nzc1NjJ9.n9PQX8w8ocKo0dMCw3g8bKhjB8Wo7f7IONFBDqfxKhs' \
--data ''

1. If your request is successful, the response will include an access token. This token is a string of characters that serves as your authentication credential for subsequent API requests. Retrieve the access token to interact with the APIs.

HTTP status codes

The IONOS APIs use the following standard HTTP response codes:

Status code	Message	Description
200	OK	It indicates that the server has successfully processed the request.
201	Created	It indicates that the request has been fulfilled, resulting in the creation of a new resource.
202	Accepted	It indicates that the request has been accepted for processing, but the processing has not been completed yet.
204	No Content	It indicates that the server successfully processed the request, but there is no content to return in the response payload.
400	Bad Request	It indicates that the server cannot process the client's request due to invalid syntax or parameters.
401	Unauthorized	It indicates that the request requires user authentication and the client needs to provide valid credentials for access.
403	Forbidden	It indicates that the server understood the request, but the client does not have permission to access the requested resource.
404	Not Found	It indicates that the requested resource could not be found on the server.
409	Conflict	It indicates that the request could not be completed due to a conflict with the current state of the resource.
422	Unprocessable Entity	It indicates that the server understands the request, but it cannot process it due to semantic errors.
429	Too Many Requests	It indicates that the client has exceeded the rate limit or quota for accessing the server, and the request has been rejected.
500	Internal Server Error	It indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
503	Service Unavailable	It indicates that the server is temporarily unable to handle the request due to overloading or maintenance.

Supported version and authorization methods

API	Version	Supported Authorization Methods
Activity Log Service	v1	Bearer Token
API Gateway	v1	Bearer Token
AI Model Hub OpenAI compatible	v1	Bearer Token
AI Model Hub	v1	Bearer Token
Auth	v1	Basic Auth and Bearer Token
CDN	v1	Bearer Token
Certificate Manager Service	v1	Basic Auth and Bearer Token
Cloud Billing	v3	Basic Auth
Cloud	v6	Basic Auth and Bearer Token
Cloud DNS	v1	Bearer Token
Container Registry	v1	Basic Auth and Bearer Token
DBaaS In-Memory DB	v1	Bearer Token
DBaaS MariaDB	v1	Bearer Token
DBaaS MongoDB	v1	Basic Auth and Bearer Token
DBaaS PostgreSQL	v1	Basic Auth and Bearer Token
Identity	v1	Bearer Token
Logging Service	v1	Bearer Token
Managed Stackable Data Platform	v1	Basic Auth and Bearer Token
Monitoring Service	v1	Basic Auth and Bearer Token
Monitoring as a Service (Legacy)	v1	Basic Auth and Bearer Token
Network File Storage	v1	Bearer Token
Quota	v1	Basic Auth and Bearer Token
Reseller	v2	Basic Auth and Bearer Token
S3 Management	v1	Bearer Token
S3 Object Storage (contract-owned buckets)	v2	Hash-Based Message Authentication Codes (HMAC)
S3 Object Storage (user-owned buckets)	v2	Hash-Based Message Authentication Codes (HMAC)
VM Auto Scaling	v1	Basic Auth
VPN Gateway	v1	Bearer Token

Request schema

It is the format of the data that is being sent in the request body when interacting with an API endpoint. Request schema has all expected properties, data types, and constraints or validations that should be applied to the request payload. The request schema is specified using JSON Schema or another schema definition language supported by OpenAPI.

Path parameters

Path parameters allow dynamic routing, and you can request different resources using a common endpoint structure. This does not include the host or base path of the API. For example, in /datacenter/{datacenterId}, the path parameter is datacenterId.

Path parameter	Type	Required	Description
datacenterId	string	Yes	The unique identifier of the datacenter.

Query parameters

Parameters that are appended to the URL to customize the request and filter data. For example, in /datacenters?depth=###, the query parameter is depth.

Query parameter	Type	Required	Description
depth	int	Optional	The depth of query parameter used to specify how many levels of URIs should be expanded.

Header parameters

Custom headers are expected as part of the request and are sent in the header section. They are usually used for authentication tokens, content type negotiation, caching directives, and other metadata related to the request. HTTP Headers are an important part of the API request and response as they represent the meta-data associated with the API request and response.

Note: RFC7230 states header names are case insensitive.

For IONOS S3 Object Storage, the headers carry information that is compatible with the S3 standard and, therefore, may require specific headers for certain operations.

The following IONOS APIs use the header parameters:

API	Supported Header Parameter
Cloud	X-Contract-Number
S3 Object Storage	Content-MD5, x-amz-acl, x-amz-grant-full-control, x-amz-grant-read-acp, x-amz-grant-write, x-amz-grant-write-acp

The following is the description of the header parameters used in IONOS APIs:

Header parameter	Type	Description
X-Contract-Number	string	It specifies the contract number associated with the account making the request in the IONOS API. It is only required for the reseller master contract users if they are using Basic Auth as an authentication method. All other users can skip this header.
Content-MD5	string	It contains a base64-encoded MD5 hash of the request body content, ensuring data integrity during transmission.
x-amz-acl	string	It sets access control permissions for the resource, defining who can access it.
x-amz-grant-full-control	string	It grants full control permissions over the resource to the specified users or groups.
x-amz-grant-read-acp	string	It grants permission to read the Access Control Policy (ACP) for the specified resource.
x-amz-grant-write	string	It grants write permissions to the specified users or groups for the resource.
x-amz-grant-write-acp	string	It grants permission to write to the Access Control Policy (ACP) for the specified resource.

Request body

The request body is described using a schema that defines the structure and format of the data expected in the body of the request. This schema can include parameters, JSON, XML, or other data formats specific to the API design. This data is then sent by the client to the server in an HTTP request.

Request

For example, for GET request for /cloudapi/v6/datacenters API, we have the following request body sample:

Example

 {
   "properties":{
      "name":"Test resource",
      "description":"My Production Datacenter",
      "location":"us/las",
      "secAuthProtection":false
   },
   "entities":{
      "servers":{
         "_links":{
            
         }
      },
      "volumes":{
         "_links":{
            
         }
      },
      "loadbalancers":{
         "_links":{
            
         }
      },
      "lans":{
         "_links":{
            
         }
      }
   }
}

Response

Status code	Response	Description
202	Accepted	The request is received and accepted for processing. The creation process is still ongoing, and the server will need some time to complete the creation of the datacenter resource before returning a final response.

Note: This example is for the CloudAPI with a successful acceptance returned with HTTP 202; this could be different for other APIs. For CloudAPI, resources are created asynchronously and handled by other endpoints. You can check for the progress via the Status URL that is returned in the response header of the POST or PUT call.

Example: GET https://api.ionos.com/cloudapi/v6/requests/abcxea-0001-9910-Y1Y2-aXXAAbnxxa/status can be used to check the processing state of your request.

Status URL in Reponse Headers

Once the datacenter resource is created, you will get a response.

Example

{
  "id": "xxxxea-0002-9925-X1X2-aXUAUnnana",
  "type": "datacenter",
  "href": "https://api.ionos.com/cloudapi/v6/datacenters/xxxxea-0002-9925-X1X2-aXUAUnnana",
  "metadata": {
    "etag": "xxxuxea-0002-9925-X1X2-aXUAUnnanahaha",
    "createdDate": "2024-03-27T14:06:49Z",
    "createdBy": "[e-mail]",
    "createdByUserId": "xgaga-1c1d-4387-iaif1-6ee95d30e54a",
    "lastModifiedDate": "2024-03-27T14:06:49Z",
    "lastModifiedBy": "[e-mail]",
    "lastModifiedByUserId": "xgaga-1c1d-4387-iaif1-6ee95d30e54a",
    "state": "BUSY"
  },
  "properties": {
    "name": "Test resource",
    "description": "My Production Datacenter",
    "location": "us/las",
    "version": null,
    "features": [],
    "secAuthProtection": false,
    "cpuArchitecture": [],
    "ipv6CidrBlock": null
  },
  "entities": {
    "servers": {
      "id": "850bd18e-3602-4b25-b1b2-a6b3eb3a41f8/servers",
      "type": "collection",
      "href": "https://api.ionos.com/cloudapi/v6/datacenters/xxxxea-0002-9925-X1X2-aXUAUnnana/servers",
      "_links": {}
    },
    "volumes": {
      "id": "850bd18e-3602-4b25-b1b2-a6b3eb3a41f8/volumes",
      "type": "collection",
      "href": "https://api.ionos.com/cloudapi/v6/datacenters/xxxxea-0002-9925-X1X2-aXUAUnnana/volumes",
      "_links": {}
    },
    "loadbalancers": {
      "id": "850bd18e-3602-4b25-b1b2-a6b3eb3a41f8/loadbalancers",
      "type": "collection",
      "href": "https://api.ionos.com/cloudapi/v6/datacenters/xxuxea-0002-9925-X1X2-aXUAUnnanahaha/loadbalancers",
      "_links": {}
    },
    "lans": {
      "id": "850bd18e-3602-4b25-b1b2-a6b3eb3a41f8/lans",
      "type": "collection",
      "href": "https://api.ionos.com/cloudapi/v6/datacenters/xxuxea-0002-9925-X1X2-aXUAUnnanahaha/lans",
      "_links": {}
    }
  }
}