### Example API Access Key URL

Source: https://github.com/zerossl/documentation/blob/main/api/index.md

An example demonstrating how to include your unique API access key in a GET request. Replace 'example_endpoint' and 'EXAMPLE_KEY' with actual values.

```text
api.zerossl.com/example_endpoint?access_key=EXAMPLE_KEY
```

--------------------------------

### Install Certificate with acme.sh using EAB

Source: https://context7.com/zerossl/documentation/llms.txt

Shows how to install a certificate obtained via acme.sh, specifying output file paths for the certificate, key, and fullchain. It also includes a command to reload the Nginx web server after installation. Ensure paths and reload command are appropriate for your setup.

```bash
# ACME server URL
ACME_SERVER="https://acme.zerossl.com/v2/DV90"

# Install certificate with automatic renewal
acme.sh --install-cert -d example.com \
  --cert-file /etc/nginx/ssl/example.com.crt \
  --key-file /etc/nginx/ssl/example.com.key \
  --fullchain-file /etc/nginx/ssl/example.com-fullchain.crt \
  --reloadcmd "systemctl reload nginx"
```

--------------------------------

### API Response Example for Downloaded Certificate

Source: https://github.com/zerossl/documentation/blob/main/api/download-certificate-inline.md

This example shows the expected JSON response when successfully downloading a certificate inline. The response contains the primary certificate and the certificate bundle, each Base64 encoded within a string.

```json
{
    "certificate.crt": "---BEGIN CERTIFICATE---{primary_certificate}---END CERTIFICATE---",
    "ca_bundle.crt": "---BEGIN CERTIFICATE---{certificate_bundle}---END CERTIFICATE---"
}
```

--------------------------------

### Authenticate ZeroSSL API Requests with Access Key

Source: https://context7.com/zerossl/documentation/llms.txt

Demonstrates how to authenticate API requests using an access key, which is required for all interactions with the ZeroSSL REST API. This includes examples for both GET and POST requests.

```bash
# Example API request with access key
curl "https://api.zerossl.com/certificates?access_key=YOUR_ACCESS_KEY"
```

```bash
# Alternative: JSON request with Content-Type header
curl -X POST "https://api.zerossl.com/certificates?access_key=YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "certificate_domains": "example.com,www.example.com",
    "certificate_validity_days": 90,
    "certificate_csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC...your CSR here...==\n-----END CERTIFICATE REQUEST-----",
    "strict_domains": 1
  }'
```

--------------------------------

### Example ZeroSSL Certificate API Response

Source: https://github.com/zerossl/documentation/blob/main/api/get-certificate.md

This is an example of a successful JSON response when retrieving certificate details from the ZeroSSL API. It includes information such as the certificate ID, common name, expiration date, status, and validation details for both email and file/CNAME methods.

```JSON
{
    "id": "a856a39a1c3ad0s8asa606g37667d221",
    "type": "1",
    "common_name": "domain.com",
    "additional_domains": "www.domain.com",
    "created": "2020-04-29 09:04:19",
    "expires": "2020-07-28 00:00:00",
    "status": "draft",
    "validation_type": null,
    "validation_emails": null,
    "replacement_for": "",
    "fingerprint_sha1": null,
    "brand_validation": null,
    "signature_algorithm_properties": "sha384WithRSAEncryption:2048",
    "validation": {
        "email_validation": {
            "domain.com": [
                "admin@domain.com",
                "administrator@domain.com",
                "hostmaster@domain.com",
                "postmaster@domain.com",
                "webmaster@domain.com"
            ]
        },
        "other_methods": {
            "domain.com": {
                "file_validation_url_http": "http://domain.com/.well-known/pki-validation/2449B.txt",
                "file_validation_url_https": "https://domain.com/.well-known/pki-validation/2449B.txt",
                "file_validation_content": [
                    "2B449B722B449B729394793947",
                    "comodoca.com",
                    "4bad7360c7076ba"
                ],
                "cname_validation_p1": "2B449B7293947.domain.com",
                "cname_validation_p2": "2B449B7293947.23DD7293947.11DD7293941.ca.com"
            },
            "www.domain.com": {
                "file_validation_url_http": "http://www.domain.com/.well-known/pki-validation/2449B.txt",
                "file_validation_url_https": "https://www.domain.com/.well-known/pki-validation/2449B.txt",
                "file_validation_content": [
                    "2B449B722B449B729394793947",
                    "comodoca.com",
                    "4bad7360c7076ba"
                ],
                "cname_validation_p1": "2B449B7293947.www.domain.com",
                "cname_validation_p2": "2B449B7293947.23DD7293947.11DD7293941.ca.com"
            }
        }
    }
}
```

--------------------------------

### Use EAB Credentials with acme.sh (Registration and Issuance)

Source: https://context7.com/zerossl/documentation/llms.txt

Illustrates how to register an account with ZeroSSL using EAB credentials and then issue a certificate with the acme.sh client. This example assumes you are using the webroot challenge for domain validation. Replace placeholders with your actual credentials and domain.

```bash
acme.sh --register-account \
  --server https://acme.zerossl.com/v2/DV90 \
  --eab-kid GD-VvWydSVFuss_GhBwYQQ \
  --eab-hmac-key MjXU3MH-Z0WQ7piMAnVsCpD1shgMiWx6ggPWiTmydgUaj7dWWWfQfA

acme.sh --issue -d example.com -d www.example.com \
  --server https://acme.zerossl.com/v2/DV90 \
  --webroot /var/www/html
```

--------------------------------

### Example API Response for Listing Certificates

Source: https://github.com/zerossl/documentation/blob/main/api/list-certificates.md

This is an example of a successful JSON response when listing certificates via the ZeroSSL API. It includes pagination details, certificate usage information, and an array of certificate objects, each containing details like ID, common name, expiry date, and status. The structure may vary slightly based on the certificate type and plan.

```json
{
    "total_count": 11,
    "result_count": 10,
    "page": 1,
    "limit": 10,
    "acmeUsageLevel": "LOW",
    "isAcmeLocked": false,
    "results": [
        {
            "id": "a856a39a1c3ad0s8asa606g37667d221",
            "type": "1",
            "common_name": "domain.com",
            "additional_domains": "www.domain.com",
            "created": "2020-04-29 09:04:19",
            "expires": "2020-07-28 00:00:00",
            "status": "draft",
            "validation_type": null,
            "validation_emails": null,
            "replacement_for": "",
            "fingerprint_sha1": null,
            "brand_validation": null,
            "signature_algorithm_properties": "sha384WithRSAEncryption:2048",
            "validation": {
                "email_validation": {
                    "domain.com": [
                        "admin@domain.com",
                        "administrator@domain.com",
                        "hostmaster@domain.com",
                        "postmaster@domain.com",
                        "webmaster@domain.com"
                    ]
                },
                "other_methods": {
                    "domain.com": {
                        "file_validation_url_http": "http://domain.com/.well-known/pki-validation/2449B.txt"
                    }
                }
            }
        }
    ]
}
```

--------------------------------

### Certbot with HTTP-01 Challenge using EAB

Source: https://context7.com/zerossl/documentation/llms.txt

Example of using Certbot with the HTTP-01 challenge to obtain SSL certificates via ZeroSSL's ACME endpoint. This requires the webroot directory to be accessible by the webserver. Replace YOUR_EAB_KID and YOUR_EAB_HMAC_KEY with your actual credentials.

```bash
# ACME server URL
ACME_SERVER="https://acme.zerossl.com/v2/DV90"

# Example: Certbot with HTTP-01 challenge
certbot certonly --webroot \
  -w /var/www/html \
  --server $ACME_SERVER \
  --eab-kid YOUR_EAB_KID \
  --eab-hmac-key YOUR_EAB_HMAC_KEY \
  -d example.com \
  -d www.example.com
```

--------------------------------

### GET /certificates/{certificate_id}/download

Source: https://context7.com/zerossl/documentation/llms.txt

Download issued certificate files as a compressed ZIP archive. Once a certificate is issued, download all certificate files packaged in a ZIP archive.

```APIDOC
## Download Certificate as ZIP

### Description
Download issued certificate files as a compressed ZIP archive.

### Method
GET

### Endpoint
`/certificates/{certificate_id}/download`

### Parameters
#### Query Parameters
- **access_key** (string) - Required - Your ZeroSSL API access key.
- **include_cross_signed** (integer) - Optional - Set to `1` to include the cross-signed certificate for legacy compatibility.

#### Path Parameters
- **certificate_id** (string) - Required - The unique ID of the certificate.

### Request Example
```bash
# Download certificate as ZIP file
curl "https://api.zerossl.com/certificates/a856a39a1c3ad0s8asa606g37667d221/download?access_key=YOUR_ACCESS_KEY" \
  --output certificate.zip

# Download with cross-signed certificate for legacy compatibility
curl "https://api.zerossl.com/certificates/a856a39a1c3ad0s8asa606g37667d221/download?access_key=YOUR_ACCESS_KEY&include_cross_signed=1" \
  --output certificate.zip
```

### Response
#### Success Response (200)
A ZIP archive containing the certificate files (`certificate.crt` and `ca_bundle.crt`).
```

--------------------------------

### Retrieve Certificate Details via HTTPS GET

Source: https://github.com/zerossl/documentation/blob/main/api/get-certificate.md

Make an HTTPS GET request to the ZeroSSL API's `certificates` endpoint, providing the certificate ID in the URL. This method requires your `access_key` and the certificate's `{id}` as parameters to fetch detailed certificate information, including its status, domain names, and validation details.

```HTTP
GET https://api.zerossl.com/certificates/{id}?access_key=YOUR_ACCESS_KEY
```

--------------------------------

### Get Certificate

Source: https://github.com/zerossl/documentation/blob/main/api/get-certificate.md

Retrieves information about an existing SSL certificate using its ID.

```APIDOC
## GET /certificates/{id}

### Description
Retrieves information about an existing certificate using the ZeroSSL API by making an HTTPS GET request to the `certificates` endpoint and passing the certificate ID (hash) to the URL.

### Method
GET

### Endpoint
`https://api.zerossl.com/certificates/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier (hash) of the certificate.

#### Query Parameters
- **access_key** (string) - Required - Your ZeroSSL API access key.

### Request Example
```json
{
  "access_key": "YOUR_ACCESS_KEY"
}
```

### Response
#### Success Response (200)
- **id** (string) - The internal certificate ID (hash).
- **type** (integer) - Numeric ID identifying the certificate type: `1` (90-day), `2` (90-day wildcard), `3` (90-day multi-domain), `4` (1-year), `5` (1-year wildcard), `6` (1-year multi-domain).
- **common_name** (string) - The common name of the certificate (e.g., `domain.com`).
- **additional_domains** (string) - Any additional domains (SANs) included in the certificate.
- **created** (string) - The exact time (UTC) the certificate was created (e.g., `2020-04-29 09:04:19`).
- **expires** (string) - The exact time (UTC) the certificate will expire (e.g., `2020-07-28 00:00:00`).
- **status** (string) - The current certificate status. Possible values: `draft`, `pending_validation`, `issued`, `revoked`, `cancelled`, `expired`.
- **validation_type** (string|null) - The type of domain verification. Possible values: `EMAIL`, `CNAME_CSR_HASH`, `HTTP_CSR_HASH`, `HTTPS_CSR_HASH`, or `null` if not initiated.
- **validation_emails** (string|null) - Selected verification emails if email verification is chosen.
- **replacement_for** (string) - The ID of the certificate this one is replacing, if applicable.
- **fingerprint_sha1** (string|null) - The SHA-1 fingerprint of the certificate (if issued).
- **brand_validation** (boolean|null) - Indicates if manual brand review is required.

#### Response Example
```json
{
    "id": "a856a39a1c3ad0s8asa606g37667d221",
    "type": "1",
    "common_name": "domain.com",
    "additional_domains": "www.domain.com",
    "created": "2020-04-29 09:04:19",
    "expires": "2020-07-28 00:00:00",
    "status": "draft",
    "validation_type": null,
    "validation_emails": null,
    "replacement_for": "",
    "fingerprint_sha1": null,
    "brand_validation": null,
    "signature_algorithm_properties": "sha384WithRSAEncryption:2048",
    "validation": {
        "email_validation": {
            "domain.com": [
                "admin@domain.com",
                "administrator@domain.com",
                "hostmaster@domain.com",
                "postmaster@domain.com",
                "webmaster@domain.com"
            ]
        },
        "other_methods": {
            "domain.com": {
                "file_validation_url_http": "http://domain.com/.well-known/pki-validation/2449B.txt",
                "file_validation_url_https": "https://domain.com/.well-known/pki-validation/2449B.txt",
                "file_validation_content": [
                    "2B449B722B449B729394793947",
                    "comodoca.com",
                    "4bad7360c7076ba"
                ],
                "cname_validation_p1": "2B449B7293947.domain.com",
                "cname_validation_p2": "2B449B7293947.23DD7293947.11DD7293941.ca.com"
            },
            "www.domain.com": {
                "file_validation_url_http": "http://www.domain.com/.well-known/pki-validation/2449B.txt",
                "file_validation_url_https": "https://www.domain.com/.well-known/pki-validation/2449B.txt",
                "file_validation_content": [
                    "2B449B722B449B729394793947",
                    "comodoca.com",
                    "4bad7360c7076ba"
                ],
                "cname_validation_p1": "2B449B7293947.www.domain.com",
                "cname_validation_p2": "2B449B7293947.23DD7293947.11DD7293941.ca.com"
            }
        }
    }
}
```
```

--------------------------------

### Download Certificate (inline) HTTPS GET Request

Source: https://github.com/zerossl/documentation/blob/main/api/download-certificate-inline.md

This snippet demonstrates how to construct an HTTPS GET request to download a certificate inline. It requires your access key and the certificate ID. An optional parameter `include_cross_signed` can be used to include cross-signed certificates.

```http
GET https://api.zerossl.com/certificates/{id}/download/return?access_key=YOUR_ACCESS_KEY&include_cross_signed=1
```

--------------------------------

### HTTP File Validation Error Slugs

Source: https://github.com/zerossl/documentation/blob/main/api/verify-domains.md

A reference guide to the different error slugs returned during HTTP file validation failures.

```APIDOC
## HTTP File Validation Error Slugs

### Description
This section explains the granular error reporting slugs available for HTTP file validation failures, helping you diagnose and resolve issues more effectively.

### Error Slug Reference

| Error Slug            | Description                                                                                                                                    |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `http_transport_failed` | Returned if there was a connection problem. Reasons can be that the host cannot be resolved or your server is not reachable. Check file availability. Retrying might resolve temporary issues. |
| `bad_response_code`   | The server did not respond with HTTP code 200 (OK). Most likely the validation file was not placed correctly (404). Redirections (3xx) are not allowed. |
| `timeout`             | The request to the server timed out. Check if your server responds very slowly. If not, simply retry the API call.                              |
| `bad_file_content`    | The validation file cannot be read or is corrupted.                                                                                            |
| `wrong_file_content`  | Your file does not contain the exact content required for validation.                                                                            |
```

--------------------------------

### List Certificates HTTPS GET Request

Source: https://github.com/zerossl/documentation/blob/main/api/list-certificates.md

This snippet demonstrates how to construct an HTTPS GET request to the ZeroSSL API to list certificates. It includes common parameters like access key, status, and search terms. Ensure you replace placeholders with your actual API key and desired parameters. Note that high volume limitations may apply.

```bash
curl -X GET \
  'https://api.zerossl.com/certificates?access_key=YOUR_ACCESS_KEY&certificate_status=issued&limit=100&page=1'
```

--------------------------------

### Use EAB Credentials with Certbot

Source: https://context7.com/zerossl/documentation/llms.txt

Shows how to use ZeroSSL's EAB credentials with the Certbot ACME client for obtaining SSL/TLS certificates. This example uses the standalone mode for domain verification. Ensure you replace placeholder values with your actual EAB credentials and domain names.

```bash
certbot certonly --standalone \
  --server https://acme.zerossl.com/v2/DV90 \
  --eab-kid GD-VvWydSVFuss_GhBwYQQ \
  --eab-hmac-key MjXU3MH-Z0WQ7piMAnVsCpD1shgMiWx6ggPWiTmydgUaj7dWWWfQfA \
  -d example.com -d www.example.com
```

--------------------------------

### Get EAB Credentials for ZeroSSL

Source: https://context7.com/zerossl/documentation/llms.txt

Demonstrates how to obtain EAB (Email-to-Account Binding) credentials from the ZeroSSL API. These credentials include a Key ID (kid) and a HMAC key required for authenticating with ACME clients.

```json
{
  "success": 1,
  "eab_kid": "GD-VvWydSVFuss_GhBwYQQ",
  "eab_hmac_key": "MjXU3MH-Z0WQ7piMAnVsCpD1shgMiWx6ggPWiTmydgUaj7dWWWfQfA"
}
```

--------------------------------

### CNAME Verification Error Response Example

Source: https://github.com/zerossl/documentation/blob/main/api/verify-domains.md

This JSON object represents an error response from the ZeroSSL API when CNAME verification fails. It details which domains could not be verified and provides specific information about the expected CNAME record, the actual record found, and whether the CNAME was found at all.

```JSON
{
    "success": false,
    "error": {
        "code": 0,
        "type": "domain_control_validation_failed",
        "details": {
            "domain.com": {
                "domain.com": {
                    "cname_found": 0,
                    "record_correct": 0,
                    "target_host": "_2B449B729284AA7CB56014584F261FBF",
                    "target_record": "A1063BBA157D.686A709A3.4BAD7A.CA.COM",
                    "actual_record": ""
                },
                "www.domain.com": {
                    "cname_found": 0,
                    "record_correct": 0,
                    "target_host": "_2B449B729284AA7CB56014584F261FBF",
                    "target_record": "A1063BBA157D.686A709A3.4BAD7A.CA.COM",
                    "actual_record": ""
                }
            }
        }
    }
}
```

--------------------------------

### GET /certificates/{certificate_id}/status

Source: https://context7.com/zerossl/documentation/llms.txt

Monitor domain verification progress for email-validated certificates. Check the status of email-based domain verification to determine whether verification emails have been sent and if domains have been successfully verified.

```APIDOC
## Check Verification Status

### Description
Monitor domain verification progress for email-validated certificates.

### Method
GET

### Endpoint
`/certificates/{certificate_id}/status`

### Parameters
#### Query Parameters
- **access_key** (string) - Required - Your ZeroSSL API access key.

#### Path Parameters
- **certificate_id** (string) - Required - The unique ID of the certificate.

### Request Example
```bash
curl "https://api.zerossl.com/certificates/a856a39a1c3ad0s8asa606g37667d221/status?access_key=YOUR_ACCESS_KEY"
```

### Response
#### Success Response (200)
- **validation_completed** (integer) - Indicates if validation is completed (1 for completed, 0 for not completed).
- **details** (object) - Details about the verification status for each domain.
  - **[domain_name]** (object)
    - **method** (string) - The verification method used.
    - **status** (string) - The verification status (e.g., `Email Sent`, `Verified`).

#### Response Example
```json
{
  "validation_completed": 0,
  "details": {
    "example.com": {
      "method": "admin@example.com",
      "status": "Email Sent"
    },
    "www.example.com": {
      "method": "admin@www.example.com",
      "status": "Verified"
    }
  }
}
```
```

--------------------------------

### Get Certificate Details by ID

Source: https://context7.com/zerossl/documentation/llms.txt

Retrieve detailed information about a specific certificate using its unique ID. The response includes all certificate metadata, validation status, domain information, and expiration dates. This is useful for checking the current state of a certificate.

```bash
# Get certificate details by ID
curl "https://api.zerossl.com/certificates/a856a39a1c3ad0s8asa606g37667d221?access_key=YOUR_ACCESS_KEY"
```

--------------------------------

### GET /certificates/{certificate_id}

Source: https://context7.com/zerossl/documentation/llms.txt

Retrieve complete information about a specific certificate by ID. Fetch detailed information about any certificate using its unique certificate ID (hash). The response includes all certificate metadata, validation status, domain information, expiration dates, and available validation methods if the certificate is not yet issued.

```APIDOC
## Get Certificate Details

### Description
Retrieve complete information about a specific certificate by ID.

### Method
GET

### Endpoint
`/certificates/{certificate_id}`

### Parameters
#### Query Parameters
- **access_key** (string) - Required - Your ZeroSSL API access key.

#### Path Parameters
- **certificate_id** (string) - Required - The unique ID of the certificate.

### Request Example
```bash
curl "https://api.zerossl.com/certificates/a856a39a1c3ad0s8asa606g37667d221?access_key=YOUR_ACCESS_KEY"
```

### Response
#### Success Response (200)
- **id** (string) - The certificate ID.
- **type** (string) - The certificate type.
- **common_name** (string) - The common name for the certificate.
- **additional_domains** (string) - Additional domains included in the certificate.
- **created** (string) - The date and time the certificate was created.
- **expires** (string) - The expiration date and time of the certificate.
- **status** (string) - The current status of the certificate.
- **validation_type** (string) - The method used for domain validation.
- **fingerprint_sha1** (string) - The SHA1 fingerprint of the certificate.
- **signature_algorithm_properties** (string) - Details about the signature algorithm.

#### Response Example
```json
{
  "id": "a856a39a1c3ad0s8asa606g37667d221",
  "type": "1",
  "common_name": "example.com",
  "additional_domains": "www.example.com",
  "created": "2020-04-29 09:04:19",
  "expires": "2020-07-28 00:00:00",
  "status": "issued",
  "validation_type": "HTTP_CSR_HASH",
  "fingerprint_sha1": "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD",
  "signature_algorithm_properties": "sha384WithRSAEncryption:2048"
}
```
```

--------------------------------

### acme.sh with Automatic Renewal using EAB

Source: https://context7.com/zerossl/documentation/llms.txt

Example of configuring acme.sh to issue certificates with automatic renewal using ZeroSSL's ACME endpoint and EAB credentials. This command utilizes DNS challenge with Cloudflare integration. Customize DNS provider and credentials as needed.

```bash
# ACME server URL
ACME_SERVER="https://acme.zerossl.com/v2/DV90"

# Example: acme.sh with automatic renewal
acme.sh --issue \
  -d example.com \
  -d www.example.com \
  --server $ACME_SERVER \
  --dns dns_cloudflare \
  --eab-kid YOUR_EAB_KID \
  --eab-hmac-key YOUR_EAB_HMAC_KEY
```

--------------------------------

### HTTP File Validation API Error Response Example

Source: https://github.com/zerossl/documentation/blob/main/api/verify-domains.md

This JSON object represents a typical error response from the ZeroSSL API when HTTP file validation fails for one or more domains. It indicates the overall success status, the error type, and detailed information about validation failures for specific domains, including the reason for failure.

```json
{
    "success": false,
    "error": {
        "code": 0,
        "type": "domain_control_validation_failed",
        "details": {
            "zero.example-zero.com": {
                "http://zero.example.com/.well-known/pki-validation/E437B2F258578249498AA2A3708D6951.txt": {
                    "file_found": 0,
                    "error": true,
                    "error_slug": "wrong_file_content",
                    "error_info": "The validation file was found, but the contents are wrong."
                }
            },
            "one.example-one.com": {
                "http://one.example.com/.well-known/pki-validation/E437B2F258578249498AA2A3708D6951.txt": {
                    "file_found": 0,
                    "error": true,
                    "error_slug": "bad_response_code",
                    "error_info": "Server responded with status code: 404"
                }
            },
            "example.com": {
                "validation_successful": true
            }
        }
    }
}
```

--------------------------------

### Get Domain Verification Status (HTTPS GET)

Source: https://github.com/zerossl/documentation/blob/main/api/verification-status.md

Make an HTTPS GET request to the specified API endpoint to retrieve the verification status of domains associated with a certificate. This is particularly useful for Email Verification. Requires your API access key and the certificate ID.

```http
GET api.zerossl.com/certificates/{id}/status?access_key={your_access_key}
```

--------------------------------

### API Methods - Summary

Source: https://github.com/zerossl/documentation/blob/main/api/index.md

Overview of available API methods for managing SSL certificates.

```APIDOC
## API Methods

The ZeroSSL API supports various methods for certificate management.

*   **Download Certificate (.zip)**: Retrieve your SSL certificate in a zip archive.
*   **Get Verification Status**: Check the verification status of a certificate.
*   **Resend Verification Email**: Resend the domain verification email.
*   **Create Certificate**: Create a new SSL certificate (see specific endpoint documentation).
```

--------------------------------

### Get Domain Verification Status

Source: https://github.com/zerossl/documentation/blob/main/api/verification-status.md

Retrieve information about the domain verification status for a specific certificate by making an HTTPS GET request to the API endpoint.

```APIDOC
## GET /certificates/{id}/status

### Description
Retrieves the verification status of domains associated with a given certificate ID. This endpoint is primarily useful when Email Verification is the chosen domain verification method.

### Method
GET

### Endpoint
`api.zerossl.com/certificates/{id}/status`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier (hash) of the certificate.

#### Query Parameters
- **access_key** (string) - Required - Your ZeroSSL API access key.

### Request Example
```
GET https://api.zerossl.com/certificates/YOUR_CERTIFICATE_ID/status?access_key=YOUR_ACCESS_KEY
```

### Response
#### Success Response (200)
- **validation_completed** (integer) - Indicates if domain verification has been completed (1 for completed, 0 for not completed).
- **details** (object) - Contains verification information for each domain associated with the certificate.
  - **method** (string) - The verification email used for the domain.
  - **status** (string) - The current verification status of the domain.
```

--------------------------------

### Initiate Domain Verification (HTTP, CNAME, Email)

Source: https://context7.com/zerossl/documentation/llms.txt

Initiate the domain verification process for a certificate. Supports HTTP file upload, CNAME DNS records, and email verification. The choice of method affects the speed of validation. Email verification requires manual confirmation.

```bash
# Verify domains using HTTP file upload method
curl -X POST "https://api.zerossl.com/certificates/a856a39a1c3ad0s8asa606g37667d221/challenges?access_key=YOUR_ACCESS_KEY" \
  -d "validation_method=HTTP_CSR_HASH"
```

```bash
# Verify domains using CNAME DNS records
curl -X POST "https://api.zerossl.com/certificates/a856a39a1c3ad0s8asa606g37667d221/challenges?access_key=YOUR_ACCESS_KEY" \
  -d "validation_method=CNAME_CSR_HASH"
```

```bash
# Verify domains using email verification
curl -X POST "https://api.zerossl.com/certificates/a856a39a1c3ad0s8asa606g37667d221/challenges?access_key=YOUR_ACCESS_KEY" \
  -d "validation_method=EMAIL" \
  -d "validation_email=admin@example.com,admin@www.example.com"
```

--------------------------------

### POST /certificates/{certificate_id}/challenges

Source: https://context7.com/zerossl/documentation/llms.txt

Initiate domain verification using email, CNAME, or file upload methods. After creating a certificate, verify domain ownership using one of four methods: email verification, CNAME DNS record, HTTP file upload, or HTTPS file upload.

```APIDOC
## Verify Domains

### Description
Initiate domain verification using email, CNAME, or file upload methods.

### Method
POST

### Endpoint
`/certificates/{certificate_id}/challenges`

### Parameters
#### Query Parameters
- **access_key** (string) - Required - Your ZeroSSL API access key.

#### Path Parameters
- **certificate_id** (string) - Required - The unique ID of the certificate.

#### Request Body
- **validation_method** (string) - Required - The method to use for validation (e.g., `HTTP_CSR_HASH`, `CNAME_CSR_HASH`, `EMAIL`).
- **validation_email** (string) - Optional - Comma-separated list of email addresses for email validation.

### Request Example
```bash
# Verify domains using HTTP file upload method
curl -X POST "https://api.zerossl.com/certificates/a856a39a1c3ad0s8asa606g37667d221/challenges?access_key=YOUR_ACCESS_KEY" \
  -d "validation_method=HTTP_CSR_HASH"

# Verify domains using CNAME DNS records
curl -X POST "https://api.zerossl.com/certificates/a856a39a1c3ad0s8asa606g37667d221/challenges?access_key=YOUR_ACCESS_KEY" \
  -d "validation_method=CNAME_CSR_HASH"

# Verify domains using email verification
curl -X POST "https://api.zerossl.com/certificates/a856a39a1c3ad0s8asa606g37667d221/challenges?access_key=YOUR_ACCESS_KEY" \
  -d "validation_method=EMAIL" \
  -d "validation_email=admin@example.com,admin@www.example.com"
```

### Response
#### Success Response (200)
- **id** (string) - The certificate ID.
- **status** (string) - The updated status of the certificate (e.g., `pending_validation`).

#### Response Example
```json
{
  "id": "a856a39a1c3ad0s8asa606g37667d221",
  "status": "pending_validation"
}
```

#### Error Response
- **success** (boolean) - Indicates if the request was successful.
- **error** (object) - Contains error details if `success` is false.
  - **code** (integer) - The error code.
  - **type** (string) - The type of error.
  - **details** (object) - Specific details about the error.

#### Error Response Example
```json
{
  "success": false,
  "error": {
    "code": 0,
    "type": "domain_control_validation_failed",
    "details": {
      "example.com": {
        "http://example.com/.well-known/pki-validation/E437B2F.txt": {
          "file_found": 0,
          "error": true,
          "error_slug": "bad_response_code",
          "error_info": "Server responded with status code: 404"
        }
      }
    }
  }
}
```
```

--------------------------------

### POST /certificates - Create Certificate

Source: https://context7.com/zerossl/documentation/llms.txt

Create a new SSL certificate with domain validation options. Submit a POST request with certificate domains and a valid Certificate Signing Request (CSR).

```APIDOC
## POST /certificates

### Description
Create a new SSL certificate with domain validation options. To create a new SSL certificate, submit a POST request with the certificate domains and a valid Certificate Signing Request (CSR). The CSR must be 2048-bit or 4096-bit encrypted. The API returns validation methods including email verification, CNAME DNS records, and HTTP/HTTPS file upload options for domain ownership verification.

### Method
POST

### Endpoint
`/certificates`

### Parameters
#### Query Parameters
- **access_key** (string) - Required - Your ZeroSSL API access key.

#### Request Body
- **certificate_domains** (string) - Required - A comma-separated list of domains for the certificate (e.g., "example.com,www.example.com").
- **certificate_validity_days** (integer) - Required - The validity period of the certificate in days (e.g., 90).
- **certificate_csr** (string) - Required - The Certificate Signing Request (CSR) in PEM format.
- **strict_domains** (integer) - Optional - Set to 1 to enforce strict domain matching. Defaults to 0.

### Request Example

```bash
# Create a 90-day certificate for a single domain
curl -X POST "https://api.zerossl.com/certificates?access_key=YOUR_ACCESS_KEY" \
  -d "certificate_domains=example.com,www.example.com" \
  -d "certificate_validity_days=90" \
  -d "certificate_csr=-----BEGIN CERTIFICATE REQUEST-----\nMIICijCCAXICAQAwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgMClNvbWUtU3RhdGUx\nITAfBgNVBAoMGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZDCCASIwDQYJKoZIhvcN\nAQEBBQADggEPADCCAQoCggEBAM...\n-----END CERTIFICATE REQUEST-----"
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the certificate.
- **type** (string) - The type of certificate (e.g., "1" for 90-day single domain).
- **common_name** (string) - The primary common name for the certificate.
- **additional_domains** (string) - A comma-separated list of additional domains included in the certificate.
- **created** (string) - The timestamp when the certificate was created.
- **expires** (string) - The timestamp when the certificate expires.
- **status** (string) - The current status of the certificate (e.g., "draft").
- **validation** (object) - An object containing domain validation details.
  - **email_validation** (object) - Details for email validation. Keys are domain names, values are lists of available validation emails.
  - **other_methods** (object) - Details for other validation methods (e.g., HTTP file upload, CNAME).
    - **file_validation_url_http** (string) - The URL for HTTP file validation.
    - **file_validation_content** (array) - The content to be placed in the validation file.
    - **cname_validation_p1** (string) - The first part of the CNAME record for validation.
    - **cname_validation_p2** (string) - The second part of the CNAME record for validation.

#### Response Example

```json
{
  "id": "a856a39a1c3ad0s8asa606g37667d221",
  "type": "1",
  "common_name": "example.com",
  "additional_domains": "www.example.com",
  "created": "2020-04-29 09:04:19",
  "expires": "2020-07-28 00:00:00",
  "status": "draft",
  "validation": {
    "email_validation": {
      "example.com": [
        "admin@example.com",
        "webmaster@example.com"
      ]
    },
    "other_methods": {
      "example.com": {
        "file_validation_url_http": "http://example.com/.well-known/pki-validation/2449B.txt",
        "file_validation_content": [
          "2B449B722B449B729394793947",
          "comodoca.com",
          "4bad7360c7076ba"
        ],
        "cname_validation_p1": "2B449B7293947.example.com",
        "cname_validation_p2": "2B449B7293947.23DD7293947.11DD7293941.ca.com"
      }
    }
  }
}
```
```

--------------------------------

### List and Filter Certificates with ZeroSSL API

Source: https://context7.com/zerossl/documentation/llms.txt

Illustrates how to retrieve and filter existing SSL certificates using the ZeroSSL API. Supports pagination, status filtering, and domain name searches.

```bash
# List all issued certificates with pagination
curl "https://api.zerossl.com/certificates?access_key=YOUR_ACCESS_KEY&certificate_status=issued&limit=100&page=1"
```

```bash
# Search for certificates by domain name
curl "https://api.zerossl.com/certificates?access_key=YOUR_ACCESS_KEY&search=example.com"
```

```bash
# Filter by certificate type (90-day single domain)
curl "https://api.zerossl.com/certificates?access_key=YOUR_ACCESS_KEY&certificate_type=1"
```

```bash
# List certificates expiring soon
curl "https://api.zerossl.com/certificates?access_key=YOUR_ACCESS_KEY&certificate_status=expiring_soon"
```

--------------------------------

### Download Certificate Inline

Source: https://context7.com/zerossl/documentation/llms.txt

Retrieve certificate files as JSON objects for programmatic processing. Ideal for automated deployment scripts and configuration management tools.

```APIDOC
## Download Certificate Inline

Retrieve certificate files as JSON objects for programmatic processing

Download issued certificates as JSON-formatted text objects instead of a ZIP archive. This method is ideal for automated deployment scripts and configuration management tools that need to directly process certificate data without extracting files.

### Method
GET

### Endpoint
`https://api.zerossl.com/certificates/{certificate_id}/download/return`

### Parameters
#### Query Parameters
- **access_key** (string) - Required - Your ZeroSSL API access key.

### Request Example
```bash
curl "https://api.zerossl.com/certificates/a856a39a1c3ad0s8asa606g37667d221/download/return?access_key=YOUR_ACCESS_KEY"
```

### Response
#### Success Response (200)
- **certificate.crt** (string) - The content of the certificate file.
- **ca_bundle.crt** (string) - The content of the CA bundle file.

#### Response Example
```json
{
  "certificate.crt": "-----BEGIN CERTIFICATE-----\nMIIGXTCCBUWgAwIBAgIRALDh...\n-----END CERTIFICATE-----",
  "ca_bundle.crt": "-----BEGIN CERTIFICATE-----\nMIIDdzCCAl+gAwIBAgIEAgAA...\n-----END CERTIFICATE-----"
}
```

### Usage Example with jq
```bash
# Download and save certificate.crt
curl -s "https://api.zerossl.com/certificates/CERT_ID/download/return?access_key=YOUR_KEY" | \
  jq -r '."certificate.crt"' > /etc/ssl/certs/example.com.crt

# Download and save ca_bundle.crt
curl -s "https://api.zerossl.com/certificates/CERT_ID/download/return?access_key=YOUR_KEY" | \
  jq -r '."ca_bundle.crt"' > /etc/ssl/certs/ca_bundle.crt
```
```

--------------------------------

### Download Certificate (ZIP)

Source: https://github.com/zerossl/documentation/blob/main/api/download-certificate.md

Download a certificate as a ZIP file by providing the certificate ID and an access key. Optionally include a cross-signed certificate.

```APIDOC
## GET /certificates/{id}/download

### Description
Downloads an issued certificate as a ZIP file.

### Method
GET

### Endpoint
`/certificates/{id}/download`

### Parameters
#### Query Parameters
- **access_key** (string) - Required - Your API access key.
- **include_cross_signed** (integer) - Optional - Set to `1` to include the cross-signed certificate in the response.

#### Path Parameters
- **id** (string) - Required - The unique ID (hash) of the certificate to download.

### Request Example
```json
{
  "example": "https://api.zerossl.com/certificates/{id}/download?access_key=YOUR_ACCESS_KEY&include_cross_signed=1"
}
```

### Response
#### Success Response (200)
A ZIP file containing the certificate files.

#### Response Example
```json
{
  "example": "[ZIP file content]"
}
```
```

--------------------------------

### GET /api/v1/certificates/{certificateId}

Source: https://github.com/zerossl/documentation/blob/main/api/get-certificate.md

Fetches the details of a specific certificate using its unique ID. This is useful for retrieving information about issued certificates, their status, and associated metadata.

```APIDOC
## GET /api/v1/certificates/{certificateId}

### Description
Retrieves the details of a specific certificate by its unique identifier.

### Method
GET

### Endpoint
`/api/v1/certificates/{certificateId}`

### Parameters
#### Path Parameters
- **certificateId** (string) - Required - The unique identifier of the certificate to retrieve.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the certificate.
- **common_name** (string) - The common name of the certificate.
- **status** (string) - The current status of the certificate (e.g., 'issued', 'pending', 'revoked').
- **created_at** (string) - The timestamp when the certificate was created.
- **expires_at** (string) - The timestamp when the certificate expires.

#### Response Example
```json
{
  "id": "cert_abcdef1234567890",
  "common_name": "example.com",
  "status": "issued",
  "created_at": "2023-10-27T10:00:00Z",
  "expires_at": "2024-10-27T10:00:00Z"
}
```
```

--------------------------------

### Certbot with DNS-01 Challenge for Wildcard using EAB

Source: https://context7.com/zerossl/documentation/llms.txt

Demonstrates how to use Certbot with the DNS-01 challenge for wildcard certificates using ZeroSSL's ACME endpoint. This method is suitable for wildcard certificates and requires managing DNS TXT records. Replace placeholders with your actual credentials.

```bash
# ACME server URL
ACME_SERVER="https://acme.zerossl.com/v2/DV90"

# Example: Certbot with DNS-01 challenge for wildcard
certbot certonly --manual \
  --preferred-challenges dns \
  --server $ACME_SERVER \
  --eab-kid YOUR_EAB_KID \
  --eab-hmac-key YOUR_EAB_HMAC_KEY \
  -d "*.example.com" \
  -d example.com
```

--------------------------------

### Example API Error Response

Source: https://github.com/zerossl/documentation/blob/main/api/error-codes.md

This JSON object demonstrates the structure of an error response from the ZeroSSL API. It includes a 'success' flag, an error code, and a text-based error type.

```json
{
    "success": false,
    "error": {
        "code": 2803,
        "type": "certificate_not_found"
    }
}
```

--------------------------------

### Download Certificate (inline) - HTTPS GET

Source: https://github.com/zerossl/documentation/blob/main/api/download-certificate-inline.md

This endpoint allows you to download a certificate inline as JSON objects. You need to provide the certificate ID (hash) in the URL.

```APIDOC
## GET /certificates/{id}/download/return

### Description
Downloads a certificate inline as JSON objects. Pass the certificate ID (hash) to the API to the URL inside the `{id}` parameter.

### Method
GET

### Endpoint
`api.zerossl.com/certificates/{id}/download/return`

### Parameters
#### Path Parameters
- **id** (string) - Required - The certificate ID / hash.

#### Query Parameters
- **access_key** (string) - Required - Your API access key.
- **include_cross_signed** (integer) - Optional - Set to `1` to include the cross-signed certificate in the response.

### Response
#### Success Response (200)
- **certificate.crt** (string) - The primary certificate file.
- **ca_bundle.crt** (string) - The certificate bundle file.

#### Response Example
```json
{
    "certificate.crt": "---BEGIN CERTIFICATE---{primary_certificate}---END CERTIFICATE---",
    "ca_bundle.crt": "---BEGIN CERTIFICATE---{certificate_bundle}---END CERTIFICATE---"
}
```
```