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.

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": "user@example.com",
    "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": "user@example.com",
    "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

Last updated

Was this helpful?