Client

The main ACME client class.

AcmeClient

class acmeow.AcmeClient[source]

Bases: object

ACME protocol client for automated certificate management.

Implements the ACME protocol (RFC 8555) for obtaining SSL/TLS certificates from ACME-compliant certificate authorities like Let’s Encrypt.

Parameters:

  • server_url (str) – ACME server directory URL.

  • email (str) – Account email address.

  • storage_path (Path | str) – Directory for storing account and certificate data.

  • proxy_url (str | None) – URL to the proxy. Default None.

  • verify_ssl (bool | str) – Whether to verify SSL certificates. True uses the default CA bundle, False disables verification (e.g. Burp proxy), or a path string to a custom CA bundle (e.g. exported Burp CA cert). Default True.

  • timeout (int) – Request timeout in seconds. Default 30.

  • retry_config (RetryConfig | None) – Retry configuration for transient failures.

  • order_ready_timeout (int) – Maximum seconds to wait for the upstream CA to transition an order from pending to ready after authorization validation. Polled every 2 seconds. Default 30.

Example

>>> client = AcmeClient(
...     server_url="https://acme-staging-v02.api.letsencrypt.org/directory",
...     email="admin@example.com",
...     storage_path=Path("./acme_data"),
... )
>>> client.create_account()
>>> order = client.create_order([Identifier.dns("example.com")])
>>> # Complete challenges...
>>> client.finalize_order(KeyType.EC256)
>>> cert, key = client.get_certificate()
Raises:
__init__(server_url, email, storage_path, proxy_url=None, verify_ssl=True, timeout=30, retry_config=None, order_ready_timeout=30)[source]
Parameters:

  • server_url (str)

  • email (str)

  • storage_path (Path | str)

  • proxy_url (str | None)

  • verify_ssl (bool | str)

  • timeout (int)

  • retry_config (RetryConfig | None)

  • order_ready_timeout (int)

Return type:

None

property server_url: str

ACME server directory URL.

property email: str

Account email address.

property account: Account | None

Current account, or None if not created.

property order: Order | None

Current order, or None if not created.

set_dns_config(config)[source]

Set DNS verification configuration.

When configured, DNS propagation is verified before notifying the ACME server during DNS-01 challenges.

Parameters:

config (DnsConfig) – DNS verification configuration.

Return type:

None

set_external_account_binding(kid, hmac_key)[source]

Set External Account Binding (EAB) credentials.

Some ACME servers require EAB to link the ACME account to an existing account in an external system.

Parameters:

  • kid (str) – Key identifier from the CA.

  • hmac_key (str) – Base64url-encoded HMAC key from the CA.

Return type:

None

create_account(terms_agreed=True)[source]

Create or retrieve an ACME account.

Creates a new account if one doesn’t exist, or retrieves the existing account if already registered.

Parameters:

terms_agreed (bool) – Whether the user agrees to the CA’s terms of service. Must be True to create an account.

Return type:

Account

Returns:

The Account object.

Raises:
create_order(identifiers, save=True)[source]

Create a new certificate order.

Parameters:

  • identifiers (list[Identifier]) – List of identifiers (domains/IPs) for the certificate.

  • save (bool) – Whether to save order state for recovery. Default True.

Return type:

Order

Returns:

The Order object.

Raises:
load_order()[source]

Load a previously saved order.

Attempts to load and resume an incomplete order that was saved to disk. Useful for recovering from interruptions.

Return type:

Order | None

Returns:

The Order if found and still valid, None otherwise.

complete_challenges(handler, challenge_type=ChallengeType.DNS, propagation_delay=0, verify_dns=True, dns_timeout=300, parallel=False, max_workers=None)[source]

Complete all pending challenges using the provided handler.

This method sets up challenge responses, optionally verifies DNS propagation (for DNS-01), notifies the ACME server, and waits for validation to complete.

Parameters:

  • handler (ChallengeHandler) – Challenge handler for deploying/cleaning up responses.

  • challenge_type (ChallengeType) – Type of challenge to complete. Default DNS-01.

  • propagation_delay (int) – Seconds to wait after setup before notifying server. If handler has propagation_delay attribute, that value is used.

  • verify_dns (bool) – Whether to verify DNS propagation before notifying server. Only applies to DNS-01 challenges. Default True.

  • dns_timeout (int) – Maximum time to wait for DNS propagation in seconds. Default 300 (5 minutes).

  • parallel (bool) – Whether to set up and clean up challenges in parallel. Default False. Server notification and polling remain sequential.

  • max_workers (int | None) – Maximum number of parallel workers. Default None (auto). Only used when parallel=True.

Raises:
Return type:

None

complete_dns_persist_challenges(handler, preferred_issuer=None, persist_until=None, propagation_delay=None, verify_dns=True, dns_timeout=300)[source]

Complete all pending challenges using DNS-PERSIST-01.

Publishes a persistent TXT record at _validation-persist.<domain> for each pending authorization, notifies the ACME server, and waits for validation.

This is a separate method from complete_challenges() because DNS-PERSIST-01 uses neither a token nor a key authorization, and its records are meant to outlive the order. By default the records are left published so they can authorize future issuance.

An order covering both a domain and its wildcard yields two authorizations sharing one validation name; they are merged into a single record carrying policy=wildcard, which authorizes both.

The challenge type is defined by draft-ietf-acme-dns-persist, which is not yet an RFC, so the wire format may change. Offered by Let’s Encrypt staging as of July 2026.

Parameters:

  • handler (DnsPersistHandler) – Handler responsible for publishing the records.

  • preferred_issuer (str | None) – Issuer Domain Name to publish when the CA offers several. Defaults to the first name the CA offers.

  • persist_until (int | datetime | None) – Optional expiry for the record, as a UNIX timestamp or datetime. Omitted from the record when None.

  • propagation_delay (int | None) – Seconds to wait after publishing before notifying the server. Defaults to the handler’s own value.

  • verify_dns (bool) – Whether to confirm the records resolve before notifying the server. Requires DNS configuration. Default True.

  • dns_timeout (int) – Maximum time to wait for propagation. Default 300.

Raises:

  • AcmeAuthorizationError – If a pending authorization offers no DNS-PERSIST-01 challenge, or validation fails.

  • AcmeOrderError – If no order exists.

  • AcmeDnsError – If a record fails to propagate.

  • DnsPersistError – If the CA’s challenge data cannot be rendered into a valid record value.

Return type:

None

Return type:

None

>>> handler = CallbackDnsPersistHandler(upsert_txt)
>>> client.complete_dns_persist_challenges(handler)

Parameters:
finalize_order(key_type=KeyType.EC256, common_name=None, csr=None)[source]

Finalize the order by submitting a CSR.

Either generates a private key and CSR internally, or uses an externally provided CSR. When using an external CSR, the caller is responsible for managing the corresponding private key.

Parameters:

  • key_type (KeyType) – Key type for the certificate. Default EC256. Ignored when csr is provided.

  • common_name (str | None) – Common name override (defaults to first identifier). Ignored when csr is provided.

  • csr (bytes | str | None) – Externally generated CSR in PEM (str/bytes) or DER (bytes) format. When provided, no private key is generated or saved.

Raises:

  • AcmeOrderError – If finalization fails or the order does not transition to ready within order_ready_timeout seconds.

  • AcmeConfigurationError – If the provided CSR cannot be parsed.

Return type:

None

Note

The maximum wait for the CA to mark an order ready after challenge validation is controlled by order_ready_timeout on the constructor.

get_certificate(preferred_chain=None)[source]

Download the issued certificate.

Parameters:

preferred_chain (str | None) – Preferred certificate chain issuer CN. If the server provides multiple chains, select the one whose issuer CN contains this string. Default None (use default chain).

Return type:

tuple[str, str | None]

Returns:

Tuple of (certificate_pem, private_key_pem). The certificate includes the full chain. The private key is None when an external CSR was used during finalization (the caller already holds the key).

Raises:

AcmeCertificateError – If certificate download fails.

deactivate_account()[source]

Deactivate the current ACME account.

This permanently deactivates the account. Once deactivated, the account cannot be used for any further operations and cannot be reactivated.

Per RFC 8555 Section 7.3.7.

Raises:

AcmeAuthenticationError – If not authenticated or deactivation fails.

Return type:

None

update_account(email=None)[source]

Update the account contact information.

Updates the account’s contact email address with the ACME server.

Per RFC 8555 Section 7.3.2.

Parameters:

email (str | None) – New email address for the account. If None, keeps the current email.

Return type:

Account

Returns:

Updated Account object.

Raises:

AcmeAuthenticationError – If not authenticated or update fails.

key_rollover()[source]

Roll over the account key to a new key.

Generates a new account key and updates the ACME server to use it. The old key is replaced and can no longer be used.

Per RFC 8555 Section 7.3.5.

Raises:
Return type:

None

revoke_certificate(certificate, reason=None)[source]

Revoke a certificate.

Revokes the specified certificate with the ACME server.

Per RFC 8555 Section 7.6.

Parameters:

  • certificate (str | bytes) – PEM-encoded certificate string or DER-encoded bytes.

  • reason (RevocationReason | None) – Optional revocation reason code.

Raises:
Return type:

None

close()[source]

Close the client and release resources.

Return type:

None

__enter__()[source]

Context manager entry.

Return type:

AcmeClient

__exit__(*args)[source]

Context manager exit.

Return type:

None

Parameters:

args (object)