Creating a Session

Central part of the communication is a Session object. A session is used to track the communication with the ACME server.

The first step is to create a Session instance. The Session constructor expects the URI of the ACME server’s directory service, as it is documented by the CA. For example, this is how to connect to the Let’s Encrypt staging server:

Session session
    = new Session("");

However, such an URI is hard to remember and might even change in the future. For this reason, special ACME URIs should be preferred:

Session session = new Session("acme://");

Instead of a generic provider, this call uses a special Let’s Encrypt provider.


Some CAs provide metadata related to their ACME server:

Metadata meta = session.getMetadata();
URI tos = meta.getTermsOfService();
URL website = meta.getWebsite();

meta is never null, even if the server did not provide any metadata. All of the Metadata getters are optional though, and may return null if the respective information was not provided by the server.


Session.setLocale() allows to select a different locale. Errors will be returned in that language, if supported by the CA.

By default, the system’s default locale is used.


acme4j uses a standard HttpURLConnection for HTTP connections.

If a proxy must be used for internet connections, you can set a Proxy instance by invoking Session.setProxy(). An alternative is to use the system properties https.proxyHost and https.proxyPort to globally set a proxy for the Java process.

If the proxy needs authentication, you need to set a default Authenticator. Be careful: Most code snippets I have found in the internet will send out the proxy credentials to anyone who is asking. See this blog article for a good way to implement a proxy Authenticator.