Create an Auto Certificate

To work with Auto Certificate on the IONOS platform using the API, you need to create a Provider first (e.g., Let's Encrypt), and then create an Auto Certificate linked to that provider. Below are step-by-step instructions for creating a provider and an Auto Certificate using the provided API endpoints.

Prerequisites:

• This feature only works with domains that are hosted within the IONOS Cloud DNS zones. The ACME server needs to verify the domain ownership through TXT records, which are managed by the IONOS platform.

• There is currently a limit of 50 Auto Certificates.

Step 1: Create a Provider

The provider is responsible for issuing and renewing your certificates via the ACME protocol (e.g., Let's Encrypt). Here's how you can create one using the API.

API Endpoint

POST /providers

Request Body

You need to send a JSON object representing the provider details in the request body.

• name: The name of the provider (e.g., "Let's Encrypt").

• email: The email associated with the provider account.

• server: The ACME server URL (in this case, Let's Encrypt).

• externalAccountBinding (Optional): Used if you need external account binding for ACME providers like Let's Encrypt. It includes:

  • keyId: The external account key ID.

  • keySecret: The external account key secret.

Example request

POST /providers
Content-Type: application/json

{
  "metadata": {},
  "properties": {
    "name": "Let's Encrypt",
    "email": "[email protected]",
    "server": "https://acme-v02.api.letsencrypt.org/directory",
    "externalAccountBinding": {
      "keyId": "some-key-id",
      "keySecret": "secret"
    }
  }
}

Response

You will receive a response containing the Provider ID, which is needed to create an Auto Certificate.

{
  "id": "b471cd03-ef51-52c5-91a5-49195b0a04d4",
  "properties": {
    "name": "Let's Encrypt",
    "email": "[email protected]",
    "server": "https://acme-v02.api.letsencrypt.org/directory"
  }
}

Take note of the Provider ID (b471cd03-ef51-52c5-91a5-49195b0a04d4) because it will be needed in the next step.

Step 2: Create an Auto Certificate

Once the provider is created, you can create an auto-renewing certificate using that provider.

API Endpoint

POST /auto-certificates

Request Body

To create an Auto Certificate, you need to pass the Provider ID (obtained from Step 1) along with other certificate details in the request body.

• provider: The ID of the provider created in Step 1.

• commonName: The main domain name for the certificate, for example www.example.com. This field supports wildcards, for example *.example.com.

• keyAlgorithm: The key algorithm to be used (e.g., rsa4096).

• name: A human-readable name for the Auto Certificate.

• subjectAlternativeNames: (Optional) Additional domain names that the certificate should cover, for example app.example.com. This field supports wildcards, for example *.example.com. There is a limit of 10 alternative names.

Example Request

POST /auto-certificates
Content-Type: application/json

{
  "metadata": {},
  "properties": {
    "provider": "b471cd03-ef51-52c5-91a5-49195b0a04d4",  # This is the provider ID from Step 1
    "commonName": "www.example.com",
    "keyAlgorithm": "rsa4096",
    "name": "My Auto Renewed Certificate",
    "subjectAlternativeNames": [
      "app.example.com"
    ]
  }
}

Result: Upon successful creation, the API will return a response with the details of the newly created Auto Certificate.

Step 3 (Optional): Verify the Certificate

After creating the Auto Certificate, you can verify it was created correctly using the following API endpoints.

API Endpoint

GET /certificates/{certificateId}

This allows you to check the details of a specific certificate by its ID.

Example Request

GET /certificates/b471cd03-ef51-52c5-91a5-49195b0a04d4

Using filters

You can also filter the certificates by Auto Certificate UUID or common name to list relevant certificates.

• Filter by Auto Certificate UUID:

  GET /certificates?filter.autoCertificate=feac4232-bf71-4fbe-879d-4865063f2748

• Filter by domain name:

  GET /certificates?filter.commonName=www.example.com