# certbot-dns-yeil

yeil DNS Authenticator plugin for [Certbot](https://certbot.eff.org/).

Authenticates to the yeil public DNS API (`https://api.yeil.app/v1/dns`)
with a yeil **App key** (`yk_...`) sent as a Bearer token, then
adds/removes TXT records to satisfy ACME DNS-01 challenges. Works for any
yeil team with an App that has DNS record-write permission; the certbot
host just needs HTTPS reachability to `api.yeil.app`.

Wildcard certs require DNS-01, so this plugin (or another DNS
authenticator) is needed for `*.example.com`.

Full API docs: <https://docs.yeil.app/dns>.

## Installation

```sh
pip install certbot-dns-yeil
```

## Configuration

In your yeil team settings, open **Apps**, create an App, grant it DNS
**record-write** permission on the zone(s) you'll issue certs for, and
mint a key. Drop the key (`yk_...`) into a credentials INI:

```ini
dns_yeil_api_key = yk_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyy
```

`chmod 600` it.

> Migrating from 2.x: the old `dns_yeil_email` / `dns_yeil_app_password`
> login was retired with personal app passwords. Replace those two lines
> with a single `dns_yeil_api_key`.

Optional override if you're testing against a non-production API base:

```ini
dns_yeil_base_url = https://api.staging.example/v1/dns
```

## Usage

```sh
certbot certonly \
  --authenticator dns-yeil \
  --dns-yeil-credentials /etc/letsencrypt/yeil.ini \
  -d smtp.yeil.org \
  --preferred-challenges dns
```

For wildcards:

```sh
certbot certonly \
  --authenticator dns-yeil \
  --dns-yeil-credentials /etc/letsencrypt/yeil.ini \
  -d yeil.org -d '*.yeil.org'
```

## How it works

The plugin sends the App key as a Bearer token on every request to
`https://api.yeil.app/v1/dns`. For each requested name it asks the API
which of the App's zones covers the FQDN (`GET /zones?suffix_of=<fqdn>`),
creates a TXT at `_acme-challenge.<rel>` (`POST /zones/{id}/records`),
waits for propagation, and on cleanup deletes the record by id
(`DELETE /zones/{id}/records/{recordId}`).

Revoking the App key (or disabling the App) in your team settings cuts
off access cleanly. The key only carries the DNS permissions you granted
the App, so scope it to record-write on just the zones you need.

## License

MIT. See [LICENSE](LICENSE).