TLS options can be set via the :ssl option, which should be passed a hash. This hash will be passed (almost) unchanged to the corresponding openssl OpenSSL::SSL::SSLContext, so it’ll accept :ssl_version, :verify_mode, :ca_path, and all the other usual parameters you’d set yourself if you’d be establishing the OpenSSL::SSL::SSLSocket yourself.

As an example, this is how you’d disable server certificate verification:

#=> #<HTTPX::ErrorResponse:0x00007fc9fd8850a8
 @error=#<OpenSSL::SSL::SSLError: SSL_connect returned=1 errno=0 state=error: certificate verify failed (self signed certificate)>, ....

# for one request
HTTPX.get("", ssl: {verify_mode: OpenSSL::SSL::VERIFY_NONE})
#=> #<Response:5380 HTTP/1.1 @status=200 @headers={"server"=>["nginx/1.10.3 (Ubuntu)"], ....

# or if you'd like it to apply for all requests from a session:
http = HTTPX.plugin(:cookies).with(ssl: {verify_mode: OpenSSL::SSL::VERIFY_NONE})
http.get("") #=> #<Response:5380 HTTP/1.1 @status=200 
http.get("") #=> #<Response:5400 HTTP/1.1 @status=200 


The :alpn_protocols option will be (if supported) set to %w[h2 http/1.1] by default, which is what allows seamless HTTP/2 over TLS.

(Note: httpx does not support :npn_protocols by default. As long as the underlying openssl lib allows it, you can pass it as an additional option though.)


httpx will automatically set the given URL hostname as the domain to be used for Server Name Indication.

If you need to override this somehow (as in, to complete the TLS handshake with a proxy while indicating a server downstream via Host header), you can pass :hostname):

HTTPX.("", ssl: {hostname: "proxy-ssl"}, headers: {"host": ""})

Next: Timeouts