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.
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.
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.
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
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 ascainstead. careplaces 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-caorNODE_EXTRA_CA_CERTS=file.pemwhen you cannot change code that callshttps.request()(set in the environment, not in the script). https.globalAgentpools TLS sockets and reuses sessions; a customhttps.Agenttakes the TLS options once instead of repeating them per request.- Dates matter. A wrong system clock produces
CERT_NOT_YET_VALIDorCERT_HAS_EXPIREDfor perfectly good certificates. fetch()does not acceptcain its options; to trust a private authority there, useNODE_EXTRA_CA_CERTSor an undici dispatcher.- Inspect the peer with
req.on('socket', ...)orres.socket.getPeerCertificate()for subject, issuer, validity dates and fingerprints. - HTTP/2 clients use
http2.connect().