openapi: 3.0.1
info:
  title: SSL API
  description: |
    # Working with the API
    Every endpoint uses the `X-API-Key` header for authorization, to obtain the key please see the [Official Documentation](/docs/getstarted).

    This SSL API version only supports DV certificates.

    # Support
    Support questions may be posted in English: <a href='/docs/getstarted#support'>API Support</a>.

    Please note that we offer support in the business Hours Mo-Fri 9:00-17:00 EET.

    <details>
    <summary><font size="+1.5">Release notes</font></summary>

    Version 1.0.0 - Exposed read, create and unassign operations for customer certificates.

    Version 1.0.1 - Added support to retrieve the DNS/FILE authentication token and enable customers to set the TXT record/file on the infrastructure they are using.

    Version 1.0.2 - Added support to activate SSL Unlimited certificates.
    </details>
    
    # Contact
     <a href='/docs/getstarted#support'>API Support - Website</a>
  version: 1.0.0
servers:
  - url: https://api.hosting.ionos.com/ssl
    description: Production server
    variables: {}
paths:
  /v1/certificates:
    get:
      tags:
        - Certificates
      summary: Get certificates
      description: Retrieve the details for all the certificates in the current customer account.
      operationId: getCertificates
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            format: int32
            default: 1
        - name: size
          in: query
          required: false
          schema:
            type: integer
            format: int32
            default: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateList'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Validation failed response:
                  description: Validation failed response
                  value:
                    code: VALIDATION_FAILED
                    message: The page number or the page size is invalid.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                General error message:
                  description: General error message
                  value:
                    code: ERROR
                    message: General error occurred. Please try again later.
      security:
        - X-API-Key: []
    post:
      tags:
        - Certificates
      summary: Create a new certificate
      description: |-
        Request a new certificate. This requires that there is an unused SSL certificate of the respective type already purchased within the customer account. Creating a certificate is an asynchronous operation. Currently, the supported method for getting the completed state is by polling operations (see GET /v1/certificates/{id}).

        The DV authentication method is automatically selected based on the provided common name or you can provide the method by filling the authenticationMethod field. In case you provide the authentication method, you will need to prove that you have control over the domain. `DNS` method requires a TXT record on the nameservers and `FILE` method requires a file at this location: [domain]/.well-known/pki-validation/fileauth.txt. The content of the file/TXT record can be found in authenticationSummary. After that you can use DCV_READY action to complete the validation. When `EMAIL` authentication is selected,  Digicert sends an email to the email address of the hostmaster of your domain (i.e. hostmaster@example.com). You must confirm the request for the certificate via the link contained in the email.

        The CSR must be supplied when the certificate installation is managed by you.
         The CSR must use RSA with key size 2048 bits. On Linux, you can generate the CSR using OpenSSL:

            openssl req -new -newkey rsa:2048 -nodes -keyout example.key -out example.csr -subj "/C=DE/CN=example.com"

        The generated CSR will be formatted like in the following example:

            -----BEGIN CERTIFICATE REQUEST-----
            MIICaDCCAVACAQAwIzELMAkGA1UEBhMCREUxFDASBgNVBAMMC2V4YW1wbGUuY29t
            MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA1UWfeVKGB0ekYy3Yv2R6
            tNJrwEQSIPVUkd0M+3LqEOYY3O2Hq3QQ7cbpsQEwPNXasTKmE/IbG89fDmiESfsp
            v9goxkAs0CAD6G8/e7jNe8KMrYBPBV+tFx8DV5UubmBAqd7ahLK0+dDhFbmQAnbs
            CkshE9e8yuaWKijLjr2BqiIWKR+pjCnWiBr4ApfT38vYt56ImhfNfQT/HKgxsYDO
            x1AAorauzQ6Vko5VEKtaeLFemh7AKboCza6JuDDgSqj0c8TsdStu/ftOE05fErzf
            HnJaQFfkQY+C5bo72tmtexrBXdZsGDQgvOpsE8497fmYoJ/A9D+C9udGyN9U64bM
            QwIDAQABoAAwDQYJKoZIhvcNAQELBQADggEBAEHBXVLQBb5FqdEf1b7VDFeq7ZFN
            zl61jbzefL5JcMA9wlPfJiT4nhxai3ueEHcH4mhyEvONzFBbB12TeS7GtEO9T21h
            ZGXaok4UMy/XZrJXxw733BsJyEzacuzzBNbG9BP1xPfVrTWKfmsgnurCutlNXzuj
            a0bjETgKV6QHJdB8hNWMNrpW4N6GyODBHZm0hPsQkEf4wDXnKMeO7OhQo4zOeZTn
            ZR9WVxzcWfgQ7TQ5Od+mVJHc39WhMQlFzaDsHGmipJZYN/iIeP4LBymTnnM9N84K
            z1N44/dwlIP2HxW9qjUMy+Ks6eymEAgHMeF3aym2qnPBWcd92Py7OFXZhxQ=
            -----END CERTIFICATE REQUEST-----

        For more details, you can consult the following guide from Digicert:  [How to create a CSR](https://www.digicert.com/csr-creation.htm).

        When a CSR is not provided, the certificate is automatically installed on your IONOS managed website. An error will be raised if the common name is not associated with an website managed by IONOS.
      operationId: createCertificate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrollRequest'
            examples:
              SSL_STARTER request:
                description: SSL_STARTER request
                value:
                  certificateType: SSL_STARTER
                  commonName: example.com
                  csr: |-
                    -----BEGIN CERTIFICATE REQUEST-----
                    MIICaDCCAVA...Wcd92Py7OFXZhxQ=
                    -----END CERTIFICATE REQUEST-----
        required: true
      responses:
        '202':
          description: Accepted request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Certificate'
              examples:
                SSL_STARTER response:
                  description: SSL_STARTER response
                  value:
                    id: f21ca4ad-a840-4c3e-9e06-93a3c96d822a
                    certificateType: SSL_STARTER
                    authenticationMethod: FILE
                    status: PENDING
                    commonName: example.com
                    links:
                      - rel: self
                        href: /v1/certificates/f21ca4ad-a840-4c3e-9e06-93a3c96d822a
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Validation failed response:
                  description: Validation failed response
                  value:
                    code: VALIDATION_FAILED
                    message: No unused SSL items were found in your account of type SSL_STARTER.
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                No items found response:
                  description: No items found response
                  value:
                    code: NOT_FOUND
                    message: No unused SSL items were found in your account of type SSL_STARTER.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                General error response:
                  description: General error response
                  value:
                    code: ERROR
                    message: General error occurred. Please try again later.
      security:
        - X-API-Key: []
  /v1/certificates/{id}:
    get:
      tags:
        - Certificates
      summary: Get certificate details
      description: Retrieve the details for the certificate having the specified id. Use this operation to get the status of the certificate or the certificate itself after the certificate was issued.
      operationId: getCertificateDetails
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Certificate'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                No certificate found response:
                  description: No certificate found response
                  value:
                    code: NOT_FOUND
                    message: No certificate exists for the specified id.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                General error response:
                  description: General error response
                  value:
                    code: ERROR
                    message: General error occurred. Please try again later.
      security:
        - X-API-Key: []
    delete:
      tags:
        - Certificates
      summary: Unassign
      description: |-
        Unassign the certificate having the specified id. After the operation completes the slot becomes available for creating a new certificate.

        Note: The same restrictions as in Control Panel also apply for the API operation.
      operationId: unassignCertificate
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Successful response
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Validation failed response:
                  description: Validation failed response
                  value:
                    code: VALIDATION_FAILED
                    message: Failed to unassign certificate.
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                No certificate found response:
                  description: No certificate found response
                  value:
                    code: NOT_FOUND
                    message: No certificate exists for the specified id.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                General error response:
                  description: General error response
                  value:
                    code: ERROR
                    message: General error occurred. Please try again later.
      security:
        - X-API-Key: []
  /v1/certificates/quota:
    get:
      tags:
        - Certificates
      summary: Quota
      description: |-
        Get the certificate quota for a customerId

        Request for the certificate's quota. The response includes a general count section:
        'total' =  total number of certificates, the sum of used and unused certificates,
         'used' = total number of activated certificates.
        Next, the QuotaDetails section contains a list of all certificate types and their quota, total and used count.
        The Flatrate section contains a boolean value that states whether a flatrate item is present in the customer.
        Flatrate certificates will not be counted to total quota, but used certificates will be counted separately, as part of the flatrate model.
      operationId: getCertificatesQuota
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateQuota'
              examples:
                Response of a certificate's quota:
                  description: Response of a certificate's quota
                  value: |-
                    {
                      "total": 1,
                      "used": 0,
                      "quotaDetails": [
                         {
                           "total": 1,
                           "used": 0,
                           "type": "SECURE_SITE_STARTER_WILDCARD",
                         }
                       ]
                      "flatrate": {
                         "used": 1,
                         "present": true,
                       }
                    }
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                General error response:
                  description: General error response
                  value:
                    code: ERROR
                    message: General error occurred. Please try again later.
      security:
        - X-API-Key: []
  /v1/certificates/{id}/authentications/{authenticationId}:
    post:
      tags:
        - Certificates
      summary: Perform authentication action
      description: Perform action on specified authentication id. This operation can be used to complete the domain validation.
      operationId: performAuthenticationAction
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: authenticationId
          in: path
          required: true
          schema:
            type: string
        - name: action
          in: query
          description: action type
          required: true
          schema:
            type: string
            enum:
              - DCV_READY
      responses:
        '204':
          description: Successful response
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                No certificate found response:
                  description: No certificate found response
                  value:
                    code: NOT_FOUND
                    message: No certificate exists for the specified id.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                General error response:
                  description: General error response
                  value:
                    code: ERROR
                    message: General error occurred. Please try again later.
      security:
        - X-API-Key: []
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: |-
            error code:
            NOT_FOUND;
            VALIDATION_FAILED;
            DCV_FAILED - the domain validation failed;
            INVALID_CAA_ENTRY - the domain validation failed because of invalid CAA entry;
            SECURITY_REVIEW_FAILED - the domain contains sequences of characters under embargo;
            ERROR
          enum:
            - NOT_FOUND
            - VALIDATION_FAILED
            - DCV_FAILED
            - INVALID_CAA_ENTRY
            - SECURITY_REVIEW_FAILED
            - ERROR
        message:
          type: string
          description: error description
    AuthenticationSummary:
      type: object
      properties:
        id:
          type: string
        method:
          type: string
          enum:
            - DNS
            - FILE
            - EMAIL
        name:
          type: string
        content:
          type: string
        status:
          type: string
          enum:
            - WAITING_FOR_CUSTOMER
            - PENDING
            - AUTHENTICATED
            - FAILED
    CaCertificate:
      type: object
      properties:
        type:
          type: string
          enum:
            - ROOT
            - INTERMEDIATE
        certificate:
          type: string
    Certificate:
      type: object
      properties:
        id:
          type: string
        certificateType:
          type: string
          enum:
            - SSL_STARTER
            - SSL_STARTER_WILDCARD
            - SSL_BUSINESS
            - SSL_BUSINESS_WILDCARD
            - SSL_PREMIUM
        authenticationMethod:
          type: string
          enum:
            - DNS
            - FILE
            - EMAIL
        authenticationSummary:
          $ref: '#/components/schemas/AuthenticationSummary'
        status:
          type: string
          enum:
            - ACTIVE
            - PENDING
            - REPLACING
            - RENEWING
            - FAILED
            - PENDING_CA_MANUAL_VETTING
        commonName:
          type: string
        alternativeNames:
          type: array
          items:
            type: string
        validFrom:
          type: string
          format: date-time
        validUntil:
          type: string
          format: date-time
        serialNumber:
          type: string
        caOrderId:
          type: string
        replacedCertificates:
          type: array
          items:
            $ref: '#/components/schemas/ReplacedCertificate'
        certificate:
          type: string
        caCertificates:
          type: array
          items:
            $ref: '#/components/schemas/CaCertificate'
        deploymentStatus:
          type: string
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
    CertificateList:
      type: object
      properties:
        total:
          type: integer
          format: int64
        certificates:
          type: array
          items:
            $ref: '#/components/schemas/Certificate'
    Link:
      type: object
      properties:
        rel:
          type: string
        href:
          type: string
    ReplacedCertificate:
      type: object
      properties:
        id:
          type: string
        serialNumber:
          type: string
    EnrollRequest:
      required:
        - certificateType
        - commonName
      type: object
      properties:
        certificateType:
          type: string
          enum:
            - SSL_STARTER
            - SSL_STARTER_WILDCARD
            - SSL_BUSINESS
            - SSL_BUSINESS_WILDCARD
            - SSL_PREMIUM
        commonName:
          type: string
        csr:
          type: string
        authenticationMethod:
          type: string
          enum:
            - DNS
            - FILE
            - EMAIL
    CertificateQuota:
      type: object
      properties:
        total:
          type: integer
          format: int64
        used:
          type: integer
          format: int64
        quotaDetails:
          type: array
          items:
            $ref: '#/components/schemas/QuotaDetails'
        flatrate:
          $ref: '#/components/schemas/Flatrate'
    Flatrate:
      type: object
      properties:
        used:
          type: integer
          format: int64
        present:
          type: boolean
    QuotaDetails:
      type: object
      properties:
        total:
          type: integer
          format: int64
        used:
          type: integer
          format: int64
        type:
          type: string
          enum:
            - SSL_STARTER
            - SSL_STARTER_WILDCARD
            - SSL_BUSINESS
            - SSL_BUSINESS_WILDCARD
            - SSL_PREMIUM
  securitySchemes:
    X-API-Key:
      type: apiKey
      name: X-API-Key
      in: header