Configure Custom HTTPS Agent in Axios for SSL

Configuring a custom HTTPS agent in Axios allows developers to control SSL/TLS behavior directly in Node.js applications. This guide explains how to use Node's native https module to define custom Certificate Authorities (CAs), enable mutual TLS (mTLS), or manage certificate validation settings within Axios requests and instances.

Why Use a Custom HTTPS Agent?

By default, Axios relies on the underlying Node.js runtime to handle HTTPS connections using the default system-trusted Certificate Authorities. You need a custom HTTPS agent when:

• Connecting to internal servers using self-signed certificates or private CAs.
• Implementing mutual TLS (mTLS) with client certificates and private keys.
• Enforcing specific TLS protocol versions or cipher suites.
• Disabling SSL verification during local testing.

Creating and Configuring the HTTPS Agent

To configure SSL/TLS verification, use Node.js's built-in https module to create an instance of https.Agent and pass it to Axios.

1. Using a Custom CA Certificate

If your API server uses a private or self-signed CA certificate, load the CA file using the fs module and pass it to the agent:

const axios = require('axios');
const https = require('https');
const fs = require('fs');

const httpsAgent = new https.Agent({
  ca: fs.readFileSync('./path/to/ca-certificate.pem'),
  rejectUnauthorized: true, // Enforces valid certificate verification
});

axios.get('https://internal-api.example.com/data', { httpsAgent })
  .then(response => console.log(response.data))
  .catch(error => console.error('Request failed:', error.message));

2. Configuring Mutual TLS (mTLS)

When a server requires client authentication, provide your client certificate and private key to the https.Agent:

const axios = require('axios');
const https = require('https');
const fs = require('fs');

const httpsAgent = new https.Agent({
  cert: fs.readFileSync('./path/to/client-cert.pem'),
  key: fs.readFileSync('./path/to/client-key.pem'),
  ca: fs.readFileSync('./path/to/server-ca.pem'),
  rejectUnauthorized: true,
});

axios.post('https://secure-api.example.com/resource', { payload: 'data' }, { httpsAgent })
  .then(response => console.log(response.data))
  .catch(error => console.error('mTLS failed:', error.message));

3. Disabling Certificate Verification for Local Development

To bypass SSL certificate errors for local testing environments, set rejectUnauthorized to false. Do not use this setting in production environments.

const axios = require('axios');
const https = require('https');

const httpsAgent = new https.Agent({
  rejectUnauthorized: false,
});

axios.get('https://localhost:8443/api', { httpsAgent })
  .then(response => console.log(response.data))
  .catch(error => console.error(error));

Applying the Agent Globally to an Axios Instance

Instead of passing httpsAgent to every individual request, attach it to an Axios instance for global reuse across your application:

const axios = require('axios');
const https = require('https');
const fs = require('fs');

const apiClient = axios.create({
  baseURL: 'https://api.example.com',
  httpsAgent: new https.Agent({
    ca: fs.readFileSync('./certs/ca.pem'),
    keepAlive: true, // Keeps sockets active for future requests
  }),
});

// All requests using this client inherit the HTTPS agent
apiClient.get('/users')
  .then(response => console.log(response.data));