Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท HTTP, HTTPS, net, TLS, dgram and dns

Node.js https.request() method

Reference for https.request() and https.get() in Node.js: TLS options such as ca, servername and rejectUnauthorized, https.Agent, certificate inspection and errors.

https.request() is http.request() over TLS. It takes the same arguments and returns the same http.ClientRequest, but the connection is made with tls.connect(), so the options object also accepts TLS settings: which authorities to trust (ca), which name to verify (servername), client certificates (key and cert), protocol versions and more. https.get() is the same call with the method fixed to GET and end() already called.

Node verifies the server certificate by default: the chain must lead to a trusted root, the dates must be valid, and the name you connected to must appear in the certificate. If any check fails, the request emits an 'error' with a code that says which one.

NODE
https.get('https://example.com/', (res) => {
  console.log(res.statusCode);
  res.resume();
});

Try it

The demos start a local HTTPS server with an embedded throwaway certificate for localhost (created only for these examples) and talk to it from the same program.

Node.js TLS options and certificate checks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js https.Agent and session reuse

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
https.request(options[, callback])
https.request(url[, options][, callback])
https.get(options[, callback])
https.get(url[, options][, callback])
// returns http.ClientRequest
Name Description
url A string or URL beginning with https:.
HTTP options Everything from http.request(): method, headers, path, port (default 443), timeout, signal, agent.
options.ca Certificate authorities (PEM) to trust instead of the built-in list. Passing it replaces the defaults.
options.servername The name sent via SNI and used for the identity check. Defaults to host unless that is an IP address.
options.checkServerIdentity(hostname, cert) Custom name check; return an Error to reject, or undefined to accept.
options.rejectUnauthorized Default true. false skips verification (the chain and the name). Unsafe outside tests.
options.key, options.cert, options.pfx, options.passphrase Client certificate for mutual TLS.
options.minVersion, options.maxVersion, options.ciphers Restrict the protocol versions and cipher suites.
options.ALPNProtocols, options.session, options.secureContext Application protocol list, TLS session to resume, or a prebuilt secure context.
callback One-time 'response' listener.

Returns: an http.ClientRequest.

Errors: certificate problems arrive as 'error' events with codes such as DEPTH_ZERO_SELF_SIGNED_CERT, SELF_SIGNED_CERT_IN_CHAIN, UNABLE_TO_VERIFY_LEAF_SIGNATURE, CERT_HAS_EXPIRED and ERR_TLS_CERT_ALTNAME_INVALID; protocol disagreements give EPROTO (or ERR_SSL_*). Invalid options throw synchronously.

Usage notes

  • Never ship rejectUnauthorized: false. It makes the connection encrypted but unauthenticated, so anyone on the path can impersonate the server. To trust a private authority, supply it as ca instead.
  • ca replaces the default roots. If you need both the public roots and your own, concatenate them ([...tls.rootCertificates, myCa]).
  • Use the system store with --use-system-ca or NODE_EXTRA_CA_CERTS=file.pem when you cannot change code that calls https.request() (set in the environment, not in the script).
  • https.globalAgent pools TLS sockets and reuses sessions; a custom https.Agent takes the TLS options once instead of repeating them per request.
  • Dates matter. A wrong system clock produces CERT_NOT_YET_VALID or CERT_HAS_EXPIRED for perfectly good certificates.
  • fetch() does not accept ca in its options; to trust a private authority there, use NODE_EXTRA_CA_CERTS or an undici dispatcher.
  • Inspect the peer with req.on('socket', ...) or res.socket.getPeerCertificate() for subject, issuer, validity dates and fingerprints.
  • HTTP/2 clients use http2.connect().