# SSL Certificates

<a id="delete-api-v1-accounts-username-ssl-domain"></a>
#### `DELETE /api/v1/accounts/{username}/ssl/{domain}`

*Delete SSL certificate*

Remove the certificate, disable SSL on the vhost and reload the webserver.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |
| `domain` | string | yes | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `MessageResponse` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "message": "string",
  "status": "success"
}
```

**cURL example:**

```bash
curl -X DELETE \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/accounts/{username}/ssl/{domain}
```

---

<a id="get-api-v1-accounts-username-ssl-domain"></a>
#### `GET /api/v1/accounts/{username}/ssl/{domain}`

*Get SSL certificate metadata*

Returns issuer, validity window, type, file paths and renewal flag.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |
| `domain` | string | yes | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_SSLResponse_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "auto_renew": false,
    "certificate_path": "...",
    "chain_path": "...",
    "domain": "example.com",
    "issuer": "",
    "key_path": "...",
    "ssl_type": "...",
    "valid_from": "...",
    "valid_to": "...",
    "warnings": [
      "..."
    ]
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/accounts/{username}/ssl/{domain}
```

---

<a id="post-api-v1-accounts-username-ssl-domain-custom"></a>
#### `POST /api/v1/accounts/{username}/ssl/{domain}/custom`

*Upload custom SSL certificate*

Install an externally-issued certificate (PEM-encoded cert + key + optional chain).

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |
| `domain` | string | yes | — |

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `ca_bundle` | string | no | — |
| `certificate` | string | yes | minLength=1; maxLength=65536 |
| `force` | boolean | no | default `False` |
| `private_key` | string | yes | minLength=1; maxLength=65536 |

**Request body example:**

```json
{
  "ca_bundle": "string",
  "certificate": "string",
  "force": false,
  "private_key": "string"
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_SSLResponse_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "auto_renew": false,
    "certificate_path": "...",
    "chain_path": "...",
    "domain": "example.com",
    "issuer": "",
    "key_path": "...",
    "ssl_type": "...",
    "valid_from": "...",
    "valid_to": "...",
    "warnings": [
      "..."
    ]
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/accounts/{username}/ssl/{domain}/custom
```

---

<a id="post-api-v1-accounts-username-ssl-domain-letsencrypt"></a>
#### `POST /api/v1/accounts/{username}/ssl/{domain}/letsencrypt`

*Issue / renew Let's Encrypt certificate*

Runs certbot for the owned domain. Idempotent: re-issuing an already-valid certificate is a no-op unless `force_renew` or `force` is set in the body.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |
| `domain` | string | yes | — |

**Request body example:**

```json
{
  "force": false,
  "force_renew": false
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_SSLResponse_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "auto_renew": false,
    "certificate_path": "...",
    "chain_path": "...",
    "domain": "example.com",
    "issuer": "",
    "key_path": "...",
    "ssl_type": "...",
    "valid_from": "...",
    "valid_to": "...",
    "warnings": [
      "..."
    ]
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/accounts/{username}/ssl/{domain}/letsencrypt
```

---

<a id="post-api-v1-ssl-bulk-letsencrypt"></a>
#### `POST /api/v1/ssl/bulk-letsencrypt`

*Bulk Let's Encrypt issuance*

Request certificates for up to 20 (username, domain) pairs in one call. Per-entry ownership is verified before certbot is invoked. Aborts gracefully if the API client disconnects.

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `domains` | array<BulkSSLDomainEntry> | yes | — |

**Request body example:**

```json
{
  "domains": [
    {
      "domain": "example.com",
      "username": "alice"
    }
  ]
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_BulkSSLData_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "results": [
      "..."
    ],
    "summary": "..."
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/ssl/bulk-letsencrypt
```

---