> ## Documentation Index
> Fetch the complete documentation index at: https://docs.searchcompany.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Technical overview of the Start Certificate endpoint

# POST /api/domain/start-certificate/{org_id}

Initiates a Let's Encrypt certificate request for a custom domain. This is Step 1 of the zero-downtime SSL flow.

## Purpose

This endpoint starts the ACME DNS-01 challenge process:

1. Creates a new certificate order with Let's Encrypt
2. Returns a TXT record the user must add to their DNS
3. Stores the challenge data for later completion

## Architecture

```mermaid theme={null}
flowchart TD
    A[Frontend Request] --> B[Start Certificate Endpoint]
    B --> C{Existing Order?}
    C -->|Yes, Pending| D[Reuse Existing Order]
    C -->|No/Invalid| E[Create New Order]
    E --> F[ACME Client]
    F --> G[Let's Encrypt API]
    G --> H[Return Challenge]
    H --> I[Store in Database]
    D --> J[Return TXT Record]
    I --> J
```

## Internal Services

### start\_certificate\_request

Creates a new Let's Encrypt certificate order using the ACME protocol.

**Location:** `src/app/apis/domain/shared/letsencrypt/certificate_service.py`

**Returns:**

* `order_url` - URL to check order status
* `authorization_url` - URL for authorization
* `challenge_url` - URL to respond to challenge
* `finalize_url` - URL to finalize order
* `txt_record_name` - DNS TXT record name (e.g., `_acme-challenge.example.com`)
* `txt_record_value` - DNS TXT record value

## Response Fields

| Field               | Type   | Description                   |
| ------------------- | ------ | ----------------------------- |
| `txt_record_name`   | string | TXT record name to add to DNS |
| `txt_record_value`  | string | TXT record value              |
| `order_url`         | string | ACME order URL                |
| `authorization_url` | string | ACME authorization URL        |
| `challenge_url`     | string | ACME challenge URL            |
| `finalize_url`      | string | ACME finalize URL             |

## Code Location

```
src/app/apis/domain/start_certificate/routes.py
```