# Getting Started

Use the IONOS Cloud APIs to automate and integrate IONOS Cloud services.

{% stepper %}
{% step %}

### Pick the API base URL

Most APIs use `https://api.ionos.com/`.

Some services use a service-specific host.
{% endstep %}

{% step %}

### Generate an access token

Use Basic (username + password) or a secure token.

Both methods call `GET /auth/v1/tokens/generate`.
{% endstep %}

{% step %}

### Make your first request

Use the returned access token in your API calls.

```bash
curl --request GET 'https://api.ionos.com/cloudapi/v6/datacenters' \
  --header 'Authorization: Bearer <access_token>'
```

{% endstep %}
{% endstepper %}

## Base URL

Use the base URL documented for the API you call.

**Common base URL:** `https://api.ionos.com/`

## Authorization

Generate an access token, then use it in `Authorization: Bearer <access_token>`.

{% hint style="info" %}
**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 **reseller** accounts, Bearer Token Authentication improves handling because the additional header token for sub-contracts is not required.
  {% endhint %}

{% tabs %}
{% tab title="Basic Authentication" %}
Use your username and password to mint an access token.

1. Create a Base64 value of `username:password`.

   ```bash
   printf '%s' 'username:password' | base64
   ```
2. Request an access token:

   ```bash
   curl --location \
     --request GET 'https://api.ionos.com/auth/v1/tokens/generate' \
     --header 'Authorization: Basic <base64(username:password)>' \
     --data ''
   ```
3. Use the returned access token in your API calls:

   ```bash
   curl --request GET 'https://api.ionos.com/cloudapi/v6/datacenters' \
     --header 'Authorization: Bearer <access_token>'
   ```

{% endtab %}

{% tab title="Bearer Token Authentication" %}
Use a secure token to mint an access token.

1. Generate a secure token (one-time setup):
   * [Generate via DCD](https://docs.ionos.com/cloud/set-up-ionos-cloud/management/token-management#generate-authentication-token)
   * [Generate via CLI](https://docs.ionos.com/cli-ionosctl/subcommands/authentication/token/generate)
2. Request an access token using your secure token:

   ```bash
   curl --location \
     --request GET 'https://api.ionos.com/auth/v1/tokens/generate' \
     --header 'Authorization: Bearer <secure_token>' \
     --data ''
   ```
3. Use the returned access token in your API calls:

   ```bash
   curl --request GET 'https://api.ionos.com/cloudapi/v6/datacenters' \
     --header 'Authorization: Bearer <access_token>'
   ```

{% endtab %}
{% endtabs %}

## 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**            |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------: | ---------------------------------------------- |
| [<mark style="color:blue;">Activity Log Service</mark>](https://docs.ionos.com/sections-test/api-reference/observability/activity-log)                                                                                       |                            [v1](https://docs.ionos.com/sections-test/api-reference/observability/activity-log#version)                           | Bearer Token                                   |
| [<mark style="color:blue;">API Gateway</mark>](https://docs.ionos.com/sections-test/api-reference/network-services/api-gateway)                                                                                              |                         [0.0.1](https://docs.ionos.com/sections-test/api-reference/network-services/api-gateway#version)                         | Bearer Token                                   |
| [<mark style="color:blue;">AI Model Hub OpenAI compatible</mark>](https://docs.ionos.com/sections-test/api-reference/ai-model-hub-openai)                                                                                    |                                   [v1](https://docs.ionos.com/sections-test/api-reference/ai-model-hub-openai)                                   | Bearer Token                                   |
| [<mark style="color:blue;">AI Model Hub</mark>](https://docs.ionos.com/sections-test/api-reference/ai/ai-model-hub)                                                                                                          |                                     [v1](https://docs.ionos.com/sections-test/api-reference/ai/ai-model-hub)                                     | Bearer Token                                   |
| [<mark style="color:blue;">Auth</mark>](https://docs.ionos.com/sections-test/api-reference/readme/broken-reference)                                                                                                          |                                 [v1](https://docs.ionos.com/sections-test/api-reference/readme/broken-reference)                                 | Basic Auth and Bearer Token                    |
| [<mark style="color:blue;">CDN</mark>](https://docs.ionos.com/sections-test/api-reference/network-services/cdn)                                                                                                              |                                   [v1](https://docs.ionos.com/sections-test/api-reference/network-services/cdn)                                  | Bearer Token                                   |
| [<mark style="color:blue;">Certificate Manager Service</mark>](https://docs.ionos.com/sections-test/api-reference/network-services/certificate-manager)                                                                      |                           [v1](https://docs.ionos.com/sections-test/api-reference/network-services/certificate-manager)                          | Basic Auth and Bearer Token                    |
| [<mark style="color:blue;">Cloud Billing</mark>](https://docs.ionos.com/sections-test/api-reference/observability/billing-api)                                                                                               |                                [v3](https://docs.ionos.com/sections-test/api-reference/observability/billing-api)                                | Basic Auth                                     |
| [<mark style="color:blue;">Cloud</mark>](https://docs.ionos.com/sections-test/api-reference/cloud-api-v6)                                                                                                                    |                                       [v6](https://docs.ionos.com/sections-test/api-reference/cloud-api-v6)                                      | Basic Auth and Bearer Token                    |
| [<mark style="color:blue;">Cloud DNS</mark>](https://docs.ionos.com/sections-test/api-reference/network-services/cloud-dns)                                                                                                  |                                [v1](https://docs.ionos.com/sections-test/api-reference/network-services/cloud-dns)                               | Bearer Token                                   |
| [<mark style="color:blue;">Container Registry</mark>](https://docs.ionos.com/sections-test/api-reference/containers/private-container-registry)                                                                              |                          [v1](https://docs.ionos.com/sections-test/api-reference/containers/private-container-registry)                          | Basic Auth and Bearer Token                    |
| [<mark style="color:blue;">DBaaS In-Memory DB</mark>](https://docs.ionos.com/sections-test/api-reference/databases/in-memory-db)                                                                                             |                              [v1](https://docs.ionos.com/sections-test/api-reference/databases/in-memory-db#version)                             | Bearer Token                                   |
| [<mark style="color:blue;">DBaaS MariaDB</mark>](https://docs.ionos.com/sections-test/api-reference/databases/mariadb)                                                                                                       |                                    [v1](https://docs.ionos.com/sections-test/api-reference/databases/mariadb)                                    | Bearer Token                                   |
| [<mark style="color:blue;">DBaaS MongoDB</mark>](https://docs.ionos.com/sections-test/api-reference/databases/mongodb)                                                                                                       |                                    [v1](https://docs.ionos.com/sections-test/api-reference/databases/mongodb)                                    | Basic Auth and Bearer Token                    |
| [<mark style="color:blue;">DBaaS PostgreSQL</mark>](https://docs.ionos.com/sections-test/api-reference/databases/postgresql)                                                                                                 |                                   [v1](https://docs.ionos.com/sections-test/api-reference/databases/postgresql)                                  | Basic Auth and Bearer Token                    |
| [<mark style="color:blue;">Identity</mark>](https://docs.ionos.com/sections-test/api-reference/security/identity)                                                                                                            |                                    [v1](https://docs.ionos.com/sections-test/api-reference/security/identity)                                    | Bearer Token                                   |
| [<mark style="color:blue;">Logging Service</mark>](https://docs.ionos.com/sections-test/api-reference/observability/logging-service)                                                                                         |                              [v1](https://docs.ionos.com/sections-test/api-reference/observability/logging-service)                              | Bearer Token                                   |
| [<mark style="color:blue;">Managed Stackable Data Platform</mark>](https://docs.ionos.com/sections-test/api-reference/readme/broken-reference)                                                                               |                                 [v1](https://docs.ionos.com/sections-test/api-reference/readme/broken-reference)                                 | Basic Auth and Bearer Token                    |
| [<mark style="color:blue;">Monitoring Service</mark>](https://docs.ionos.com/sections-test/api-reference/observability/monitoring-service)                                                                                   |                             [v1](https://docs.ionos.com/sections-test/api-reference/observability/monitoring-service)                            | Basic Auth and Bearer Token                    |
| [<mark style="color:blue;">Monitoring as a Service (Legacy)</mark>](https://docs.ionos.com/sections-test/api-reference/readme/broken-reference)                                                                              |                                 [v1](https://docs.ionos.com/sections-test/api-reference/readme/broken-reference)                                 | Basic Auth and Bearer Token                    |
| [<mark style="color:blue;">Network File Storage</mark>](https://docs.ionos.com/sections-test/api-reference/storage-and-backup/network-file-storage)                                                                          |                        [v1.ea](https://docs.ionos.com/sections-test/api-reference/storage-and-backup/network-file-storage)                       | Bearer Token                                   |
| [<mark style="color:blue;">Quota</mark>](https://docs.ionos.com/sections-test/api-reference/readme/broken-reference)                                                                                                         |                                 [v1](https://docs.ionos.com/sections-test/api-reference/readme/broken-reference)                                 | Basic Auth and Bearer Token                    |
| [<mark style="color:blue;">Reseller</mark>](https://docs.ionos.com/sections-test/api-reference/management/reseller)                                                                                                          |                                   [v2](https://docs.ionos.com/sections-test/api-reference/management/reseller)                                   | Basic Auth and Bearer Token                    |
| [<mark style="color:blue;">IONOS Object Storage Management</mark>](https://docs.ionos.com/sections-test/api-reference/storage-and-backup/ionos-object-storage/ionos-object-storage-management)                               |         [v1](https://docs.ionos.com/sections-test/api-reference/storage-and-backup/ionos-object-storage/ionos-object-storage-management)         | Bearer Token                                   |
| [<mark style="color:blue;">IONOS Object Storage (contract-owned buckets)</mark>](https://docs.ionos.com/sections-test/api-reference/storage-and-backup/ionos-object-storage/ionos-object-storage-for-contract-owned-buckets) | [v2](https://docs.ionos.com/sections-test/api-reference/storage-and-backup/ionos-object-storage/ionos-object-storage-for-contract-owned-buckets) | Hash-Based Message Authentication Codes (HMAC) |
| [<mark style="color:blue;">IONOS Object Storage (user-owned buckets)</mark>](https://docs.ionos.com/sections-test/api-reference/storage-and-backup/ionos-object-storage/ionos-object-storage-for-user-owned-buckets)         |   [v2](https://docs.ionos.com/sections-test/api-reference/storage-and-backup/ionos-object-storage/ionos-object-storage-for-user-owned-buckets)   | Hash-Based Message Authentication Codes (HMAC) |
| [<mark style="color:blue;">VM Auto Scaling</mark>](https://docs.ionos.com/sections-test/api-reference/readme/broken-reference)                                                                                               |                                [v1.ea](https://docs.ionos.com/sections-test/api-reference/readme/broken-reference)                               | Basic Auth                                     |
| [<mark style="color:blue;">VPN Gateway</mark>](https://docs.ionos.com/sections-test/api-reference/network-services/vpn-gateway)                                                                                              |                               [v1](https://docs.ionos.com/sections-test/api-reference/network-services/vpn-gateway)                              | 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.

{% hint style="info" %}
**Note:** [<mark style="color:blue;">RFC7230</mark>](https://datatracker.ietf.org/doc/html/rfc7230#page-22) states header names are case insensitive.
{% endhint %}

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

`GET` requests usually do not include a request body.

For example, for a `POST` request to `/cloudapi/v6/datacenters`, the request body can look like this:

<details>

<summary>Example</summary>

```
{
  "properties": {
    "name": "Test resource",
    "description": "My Production Datacenter",
    "location": "us/las",
    "secAuthProtection": false
  }
}
```

</details>

### 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. |

{% hint style="info" %}
**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.
{% endhint %}

<figure><img src="https://github.com/ionos-cloud/API-Test/blob/main/images/header_example.png" alt="Status URL in Reponse Headers"><figcaption><p>Status URL in Reponse Headers</p></figcaption></figure>

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

<details>

<summary>Example</summary>

```
{
  "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": "test.tester@ionos.com",
    "createdByUserId": "xgaga-1c1d-4387-iaif1-6ee95d30e54a",
    "lastModifiedDate": "2024-03-27T14:06:49Z",
    "lastModifiedBy": "test.tester@ionos.com",
    "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": {}
    }
  }
}
```

</details>