ZeroSSL

https://github.com/zerossl/documentation
Admin
ZeroSSL provides services and an API for managing SSL certificates, supporting the ACME protocol.
Tokens:17,902
Snippets:120
Trust Score:7.1
Update:1 day ago
Show doc for...
Tokens:
Raw
### Create Certificate (JSON Request Example)

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

Example of a JSON request body for the Create Certificate endpoint, demonstrating the JSON request format.

```APIDOC
## Create Certificate (JSON Request)

### Description
Example JSON request body for creating a certificate.

### Method
POST

### Endpoint
https://zerossl.com/documentation/api/create-certificate/

### Request Body
- **certificate_domains** (string) - Required - Comma-separated list of domains.
- **certificate_validity_days** (integer) - Required - Validity period in days.
- **certificate_csr** (string) - Required - Certificate Signing Request.
- **strict_domains** (integer) - Required - Whether to enforce strict domain validation.

### Request Example
{
    "certificate_domains": "zerossl.dev",
    "certificate_validity_days": 90,
    "certificate_csr": "CSR",
    "strict_domains": 1
}

### Response
No response schema documented.
```

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

### CNAME Verification Error Response Example

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

Example JSON error response returned when CNAME verification fails. It details which domains could not be verified, including the expected target_host and target_record values and the actual_record found.

```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": ""
                }
            }
        }
    }
}
```

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

### Error Codes - Get Verification Status

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

Error codes returned when attempting to get the verification status via the ZeroSSL REST API.

```APIDOC
## Error Codes - Get Verification Status

### Description
These error codes are returned when attempting to get the domain verification status.

### Error Codes

| Error Code | Type | Description |
| --- | --- | --- |
| `2838` | `failed_getting_validation_status` | Error retrieving domain verification status. Try again and make sure Email Verification is selected. |
```

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

### Get Verification Status

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

Endpoint to retrieve the verification status of a certificate.

```APIDOC
## Get Verification Status

### Description
Retrieves the verification status of a certificate.

### Method
GET

### Endpoint
/documentation/docs/api/verification-status

### Parameters
No parameters documented.

### Response
No response schema documented.
```

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

### POST api.zerossl.com/certificates

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

Creates a new SSL certificate. Requires an access key and a certificate signing request (CSR). Optional parameters allow specifying validity days, strict domain matching, and certificate replacement.

```APIDOC
## POST api.zerossl.com/certificates

### Description
Creates a new SSL certificate using the ZeroSSL API. The request must be an HTTPS POST to the certificates endpoint.

### Method
POST

### Endpoint
api.zerossl.com/certificates

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

#### Request Body
- **certificate_domains** (string) - Required - One or multiple comma-separated domains (or IP addresses) to be secured. The first element must match the CN of the CSR.
- **certificate_csr** (string) - Required - A certificate signing request (CSR) that is 2048-bit or 4096-bit encrypted. The CN must match the first domain.
- **certificate_validity_days** (integer) - Optional - Specify 365 for 1-year certificates, default is 90. Other values are not supported.
- **strict_domains** (integer) - Optional - Set to 1 to create a certificate exactly for the domains passed, without additional SAN entries.
- **replacement_for_certificate** (string) - Optional - Certificate hash of the certificate to be replaced. The certificate must be in status 'issued' or 'expiring_soon'.

### Request Example
POST /certificates?access_key=YOUR_ACCESS_KEY HTTP/1.1
Host: api.zerossl.com
Content-Type: application/x-www-form-urlencoded

certificate_domains=example.com,www.example.com&certificate_csr=-----BEGIN CERTIFICATE REQUEST-----...&certificate_validity_days=90&strict_domains=1

### Response
#### Success Response (200)
A JSON object containing the details of the newly created SSL certificate.

#### Response Example
{
  "id": "certificate_id",
  "common_name": "example.com",
  "status": "issued",
  "validity_days": 90
}
```

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

### JSON request body sample for Create Certificate

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

Sample JSON body for the Create Certificate endpoint. Requires the Content-Type: application/json header. Lists must be sent as comma-separated strings, not arrays.

```json
{
    "certificate_domains": "zerossl.dev",
    "certificate_validity_days": 90,
    "certificate_csr": "CSR",
    "strict_domains": 1
}
```

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

### Download Certificate (.zip)

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

Endpoint to download a certificate as a ZIP file.

```APIDOC
## Download Certificate (.zip)

### Description
Downloads the certificate as a ZIP file.

### Method
GET

### Endpoint
/documentation/docs/api/download-certificate

### Parameters
No parameters documented.

### Response
No response schema documented.
```

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

### API Request URL for Verify Domains

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

The endpoint URL for initiating domain verification. Replace {id} with your certificate ID (hash).

```text
api.zerossl.com/certificates/{id}/challenges
```

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

### Download Certificate Error Codes

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

Error codes specific to the certificate download operation.

```APIDOC
## Download Certificate Error Codes

### Error Code 2832 - certificate_not_issued
- **Description**: The given certificate has not been issued yet.

### Error Code 2860 - certificate_not_downloadable
- **Description**: The certificate can currently not be downloaded.
```

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

### EAB Credentials Endpoint Error Codes

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

Lists the error codes and types returned by the ZeroSSL EAB credentials endpoint, with descriptions for each.

```APIDOC
## EAB Credentials Endpoint Error Codes

### Description
This section documents the error codes and types that the ZeroSSL EAB credentials endpoint may return. Errors are returned in JSON format, similar to the normal ZeroSSL API.

### Error Response Format
```json
{
    "success": false,
    "error": {
        "code": 2902,
        "type": "failed_creating_eab_account"
    }
}
```

### Error Codes

#### 2902 - failed_creating_eab_account
- **Description**: Your EAB credentials can not be created currently. This is usually due to maintenance or temporary downtimes, please try again later.

#### 2903 - failed_saving_eab_account
- **Description**: Your EAB credentials could not be saved. This should occur very rarely, please try again.

#### 2904 - too_many_eab_credentials_created_today
- **Description**: You have created too many EAB credentials today. EAB credentials can be re-used, we do not know any meaningful scenario where you might need those amount of credentials. Please check your implementation (in case of troubles please contact: support@zerossl.com).

#### 2905 - too_many_eab_credentials_created_for_user
- **Description**: You have created too many EAB credentials with this user. EAB credentials can be re-used, we do not know any meaningful scenario where you might need those amount of credentials. Please check your implementation (in case of troubles please contact: support@zerossl.com).

#### 2977 - caddy_legacy_user_removed
- **Description**: The Caddyserver legacy user was removed. You can use the Caddyserver with ZeroSSL in various other ways such as the API, with a ZeroSSL user account or by at least providing your email address. More information: https://github.com/caddyserver/caddy/releases/tag/v2.8.0. Be free to contact our support team in case you have any further questions.
```

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

### HTTP file validation Possible Errors

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

Describes the error response returned when domain verification via HTTP file upload fails, including the error object with details for each domain.

```APIDOC
## HTTP file validation Possible Errors

### Description
If the verification of some or all of your uploaded files fails, the API will return an error object in JSON format outlining in detail which of the domains could be verified and which could not be verified.

### Response
#### Error Response
- **success** (boolean) - Returns `false` to indicate that an API error occurred.
- **error** (object) - Returns a sub-object containing error details.
  - **code** (number) - Returns a numeric error code uniquely associated with the specific error.
  - **type** (string) - Returns a text-based error key uniquely associated with the specific error.
  - **details** (object) - Returns an object containing error details for each domain (or a pair of www and non-www domains).
    - **domain** (object) - Contains validation details for each domain.
      - **validation_successful** (boolean) - Indicates if validation was successful.
      - **file_url** (object) - Contains error details for the validation file.
        - **file_found** (number) - Returns `1` or `0` depending on whether the file was found.
        - **error** (boolean) - Indicates if an error occurred.
        - **error_slug** (string) - Returns a text-based error key uniquely associated with the specific error.
        - **error_info** (string) - Returns a human-readable description of the error.

#### Response Example
```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
            }
        }
    }
}
```
```

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

### Explanation of error response

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

Explains the error response structure and the meaning of the error slugs returned during HTTP file validation.

```APIDOC
## Explanation of error response

### Description
Explanation of example:
* *example.com*: The file was found and successfully verified
* *zero.example-zero.com*: The file was found, but the content is wrong.
* *one.example-one.com*: The server responded with status code 404, which means the file was not yet uploaded.

### Error Slugs
| Error Slug | Description |
| --- | --- |
| `http_transport_failed` | Returned if there was a connection problem. Reasons can be that the host can not be resolved or your server is not reachable. Check if the file is publicly available. This might also occur as a temporary problem, in this case just retry the API call. |
| `bad_response_code` | The server responded not with HTTP code 200 (OK). Most probably the validation file was not placed correctly (404). Note that redirections (3xx) are not allowed for the HTTP file validation. |
| `timeout` | Request to the server had a timeout. Check if your server responds very slowly. If not, just retry. |
| `bad_file_content` | The validation file can not be read or is wrong. |
| `wrong_file_content` | Your file does not contain exactly the content required. |
```

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

### HTTP file validation API Response

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

Describes the response returned when domain verification via HTTP file upload is successful, including the certificate object with status pending_validation.

```APIDOC
## HTTP file validation API Response

### Description
If the verification of your uploaded files was successful, the ZeroSSL API will return your entire certificate object with status `pending_validation`. From this moment it will take just a few seconds (in some cases, up to 5-10 minutes) for our system to validate and issue your certificate. As soon as your certificate has been issued, the certificate status will change to `issued` automatically.

### Response
#### Success Response (200)
- **certificate** (object) - The entire certificate object with status `pending_validation`.

#### Response Example
```json
{
  "certificate": {
    "status": "pending_validation"
  }
}
```
```

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

### Error Response Format

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

The API returns a JSON error object with a success flag, error code, and error type when a request fails.

```APIDOC
## Error Response Format

### Description
Whenever there is an error processing an API request, the API returns a JSON error message with a `success` field set to `false`, an error code, and a text-based error type.

### Response
#### Error Response Example
```json
{
    "success": false,
    "error": {
        "code": 2803,
        "type": "certificate_not_found"
    }
}
```

### Error Codes - General
| Error Code | Type | Description |
| --- | --- | --- |
| `101` | `invalid_access_key` | User has provided an invalid API access key. |
| `102` | `inactive_user` | You can not authenticate because your account is not active. |
| `103` | `invalid_api_function` | User has provided an invalid API function. |
| `104` | `route_not_found` | This route does not exist. Check the spelling in your request URL and also the HTTP method you are using (some endpoints can only be called using a POST request for instance). |
| `110` | `invalid_request_body` | The body of your request was wrong. Please check your request arguments. |
| `111` | `internal_server_error` | Something went wrong. If the problem persists, please contact our support team (support@zerossl.com). |
| `112` | `conflict` | The target resource can not be modified. |
| `113` | `unprocessable_entity` | The syntax of your request was correct, but your request can not be processed. |
| `114` | `conflict` | The target resource can not be modified. |
| `115` | `invalid_json_request` | You have sent a JSON request, but it can not be decoded as JSON. Please check your input. |
| `116` | `invalid_json_request_param` | You have sent an illegal parameter in your JSON request. Multidimensional arrays, objects and resources are not allowed. |
| `2800` | `incorrect_request_type` | User has made a non-supported API request. |
| `2801` | `permission_denied` | User does not have the permissions to access this resource. |
| `2802` | `missing_certificate_hash` | User has not provided a certificate ID (hash). |
| `2803` | `certificate_not_found` | The given certificate ID (hash) could not be found. |
```

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

### Error Codes - Cancel Certificate

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

Error codes returned when attempting to cancel a certificate via the ZeroSSL REST API.

```APIDOC
## Error Codes - Cancel Certificate

### Description
These error codes are returned when attempting to cancel a certificate.

### Error Codes

| Error Code | Type | Description |
| --- | --- | --- |
| `2833` | `certificate_cannot_be_cancelled` | The given certificate cannot be cancelled due to its status. |
| `2834` | `failed_cancelling_certificate` | Internal error cancelling certificate. Try again or contact support. |
```

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

### General Error Codes

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

Error codes that may be returned by various ZeroSSL API operations, including certificate validation, CAA record checks, and certificate issuance restrictions.

```APIDOC
## General Error Codes

### Error Code 2822 - failed_showing_certificate
- **Description**: The requested certificate could not be retrieved.

### Error Code 2823 - failed_validating_certificate
- **Description**: Domain verification failed and must be retried. Possible reasons include: using a restricted TLD, domain name too long (~62 characters maximum), or custom CSR using a compromised key. See common verification problems.

### Error Code 2824 - missing_validation_emails
- **Description**: User has not provided a validation email for each domain in certificate.

### Error Code 2825 - missing_validation_email
- **Description**: User has not provided a validation email for each domain in certificate.

### Error Code 2826 - internal_error_while_valdating_domain_control
- **Description**: Internal error verifying domains. Please contact support if this error occurs.

### Error Code 2827 - invalid_validation_method
- **Description**: User has provided an invalid domain verification method.

### Error Code 2828 - missing_validation_method
- **Description**: User has not provided a domain verification method.

### Error Code 2829 - incorrect_certificate_validation_type
- **Description**: User has provided an invalid domain verification method or value.

### Error Code 2830 - certificate_not_eligible
- **Description**: The given certificate is not eligible for domain verification.

### Error Code 2831 - certificate_not_ready_to_validate
- **Description**: The given certificate is not ready for domain verification.

### Error Code 2840 - invalid_caa_records_detected
- **Description**: Invalid CAA records detected for some domains. Array of affected domains can be found in `details` object. Learn more about CAA records.

### Error Code 2841 - caa_record_check_failed
- **Description**: An internal error occurred checking your CAA records. If the problem persists, contact support.

### Error Code 2842 - replacement_needs_same_common_name
- **Description**: A replacement certificate needs the same common name as its replacement.

### Error Code 2843 - ipv6_is_not_yet_supported
- **Description**: IPv6 certificates are not yet available.

### Error Code 2874 - certificate_restricted_top_level_domain
- **Description**: Unable to issue certificates for this Top-Level-Domain at the moment. Learn more.

### Error Code 2875 - certificate_premium_not_allowed
- **Description**: Not allowed to issue premium certificates, most probably due to unpaid invoices or upgrades/downgrades. Contact support if this is a mistake.

### Error Code 2877 - certificate_unsupported_top_level_domain
- **Description**: Certain TLDs are reserved for special purposes and certificates cannot be issued for them (e.g., .local, .localhost, .example, .invalid, .test). Contact support if you believe this is a mistake.
```

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

### Resend Verification Email

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

Resends all verification emails for a specific certificate. Only works when Email Verification is the selected domain verification method.

```APIDOC
## [GET] /certificates/{id}/challenges/email

### Description
Resends all verification emails for a specific certificate. Only works when Email Verification is the selected domain verification method.

### Method
GET

### Endpoint
api.zerossl.com/certificates/{id}/challenges/email

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

#### Path Parameters
- **{id}** (string) - Required - Your certificate ID / hash.

### Response
#### Success Response (200)
- **success** (integer) - Returns `1` to indicate that the API request was successful.

#### Response Example
{
    "success": 1
}
```
Tokens:
Raw