Client

lacme.client

Async ACME v2 protocol client (RFC 8555).

Provides the :class:Client class which implements the full ACME order lifecycle: account creation, order placement, challenge handling, finalization, and certificate download.

Client

Async ACME v2 client.

Usage::

async with Client(directory_url="...", account_key=key) as client:
    cert = await client.issue(["example.com"])

auto_renew async

auto_renew(*, interval_hours: float = 12.0, days_before_expiry: int = 30, on_renewed: Callable[[CertBundle], Any] | None = None) -> asyncio.Task[None]

Start a background renewal task. Requires a store.

Returns the :class:asyncio.Task running the renewal loop.

Raises:

Type	Description
ValueError	If no store was provided to the client.

check_rate_limits

check_rate_limits(domains: str | list[str]) -> RateLimitStatus

Check if issuing for domains would exceed rate limits.

Requires a rate_limit_tracker to be set on the client.

Raises:

Type	Description
ValueError	If no rate limit tracker is configured.

close async

close() -> None

Close the underlying HTTP client if we own it.

create_account async

create_account(*, contact: list[str] | None = None, terms_of_service_agreed: bool = True, only_return_existing: bool = False, eab_kid: str | None = None, eab_hmac_key: str | None = None) -> Account

Create or find an existing ACME account.

Sets the internal account URL for subsequent requests.

For CAs requiring External Account Binding (e.g. ZeroSSL), pass eab_kid and eab_hmac_key (base64url-encoded). These fall back to the values provided at Client construction time.

create_authorization async

create_authorization(identifier_value: str, *, identifier_type: IdentifierType = IdentifierType.DNS) -> Authorization

Create a pre-authorization for an identifier (RFC 8555 §7.4.1).

Requires the server to support newAuthz (optional per RFC 8555).

Parameters:

Name	Type	Description	Default
identifier_value	str	Domain name or IP address.	required
identifier_type	IdentifierType	Identifier type (default dns).	DNS

Raises:

Type	Description
RuntimeError	If the server does not expose a newAuthz endpoint.

create_order async

create_order(domains: str | list[str], *, not_before: str | None = None, not_after: str | None = None) -> Order

Create a new certificate order.

deactivate_account async

deactivate_account() -> Account

Deactivate the current account.

directory async

directory() -> Directory

Fetch and cache the ACME directory.

download_certificate async

download_certificate(url: str) -> str

Download the certificate chain via POST-as-GET.

finalize_order async

finalize_order(order: Order, csr_der: bytes) -> Order

Submit the CSR to finalize the order.

get_authorization async

get_authorization(url: str) -> Authorization

Fetch an authorization via POST-as-GET.

get_authorizations async

get_authorizations(order: Order) -> list[Authorization]

Fetch all authorizations for an order.

Fetches are serialized to avoid nonce pool contention.

issue async

issue(domains: str | list[str], *, challenge_type: str = 'http-01', challenge_map: dict[str, tuple[str, ChallengeHandler]] | None = None) -> CertBundle

Issue a certificate for the given domain(s).

Orchestrates: account → order → authorize → finalize → download.

Parameters:

Name	Type	Description	Default
domains	str | list[str]	Domain name(s) to include in the certificate.	required
challenge_type	str	Default challenge type for all domains.	'http-01'
challenge_map	dict[str, tuple[str, ChallengeHandler]] | None	Per-domain overrides mapping {domain: (challenge_type, handler)}. Domains not in the map fall back to challenge_type and the client's default challenge_handler.	None

poll_authorization async

poll_authorization(url: str, *, timeout: float | None = None) -> Authorization

Poll an authorization until it reaches a terminal state.

poll_order async

poll_order(url: str, *, timeout: float | None = None) -> Order

Poll an order until it reaches a terminal state (valid or invalid).

respond_to_challenge async

respond_to_challenge(challenge: Challenge) -> Challenge

Signal readiness for challenge validation (POST {} to challenge URL).

revoke async

revoke(cert_pem: bytes | str, *, reason: int | None = None) -> None

Revoke a certificate using the account key (RFC 8555 §7.6).

Parameters:

Name	Type	Description	Default
cert_pem	bytes | str	PEM-encoded certificate to revoke.	required
reason	int | None	Optional revocation reason code (see :class:~lacme.models.RevocationReason).	None

revoke_with_cert_key async

revoke_with_cert_key(cert_pem: bytes | str, cert_key: EllipticCurvePrivateKey, *, reason: int | None = None) -> None

Revoke a certificate using its own key pair (RFC 8555 §7.6).

Does not require an ACME account. The JWS is signed with cert_key and uses a JWK header (not KID).

rollover_key async

rollover_key(new_key: EllipticCurvePrivateKey | None = None) -> None

Roll over the account key (RFC 8555 §7.3.5).

Replaces the current account key with new_key (generated if None). On success the new key is stored if a store was provided.