SSL Pinning with Axios in Mobile and Hybrid Apps

Axios does not natively support SSL certificate pinning in mobile or hybrid application environments because it relies on high-level JavaScript networking APIs like XMLHttpRequest. In environments such as React Native, Ionic, Capacitor, or Apache Cordova, the underlying web runtime or JavaScript engine delegates TLS validation directly to the operating system or WebView. Consequently, achieving SSL certificate pinning with Axios requires intercepting requests using custom Axios adapters and routing them through native mobile networking layers that enforce certificate or public key validation.

Why Axios Cannot Pin Certificates Natively

Axios was originally designed for web browsers and Node.js environments:

• In WebViews (Ionic, Cordova, Capacitor): JavaScript executes within a standard browser sandbox. The browser engine handles the TLS handshake automatically, providing no JavaScript API to inspect or validate server certificates against a local trust store.
• In React Native: Axios relies on the global XMLHttpRequest polyfill. While this polyfill interfaces with native platform networking (such as OkHttp on Android and NSURLSession on iOS), standard implementations only validate certificates against the default system certificate authorities (CAs).

How to Implement SSL Pinning with Axios

To enforce SSL pinning while maintaining the Axios API interface, developers use custom Axios adapters that redirect network calls to native HTTP clients.

1. Using Custom Axios Adapters

Axios allows overriding its default request transport mechanism through the adapter configuration option. A custom adapter intercepts the Axios request configuration, executes the request via a native plugin capable of SSL pinning, and returns a formatted Axios response object.

import axios from 'axios';
import NativePinningClient from 'some-native-pinning-library';

const pinnedAxios = axios.create({
  adapter: async (config) => {
    const response = await NativePinningClient.request({
      url: config.url,
      method: config.method,
      headers: config.headers,
      data: config.data,
      sslPinning: {
        certs: ['my_certificate']
      }
    });

    return {
      data: response.data,
      status: response.status,
      statusText: response.statusText,
      headers: response.headers,
      config: config,
      request: {}
    };
  }
});

2. SSL Pinning in React Native

In React Native, developers typically combine Axios with native networking modules:

• Native Modules: Libraries such as react-native-ssl-pinning wrap native libraries (OkHttp certificate pinners on Android and TrustKit or AFNetworking on iOS).
• Integration Strategy: A custom Axios adapter delegates the call to the native module, which verifies the bundled .cer file or public key hash during the TLS handshake before resolving the network promise.

3. SSL Pinning in Capacitor and Cordova

In WebView-based hybrid applications, standard Axios calls must completely bypass the WebView's network layer:

• Native HTTP Plugins: Plugins like @capacitor-community/http or cordova-plugin-advanced-http execute network requests natively rather than through the WebView.
• Axios Bridge: By setting the Axios adapter to route through the native HTTP plugin, requests benefit from native TLS validation and configured certificate pins while preserving standard Axios interceptors and syntax.

Types of Pinning Supported via Native Layers

When bridging Axios to native clients, two primary pinning strategies can be used:

• Certificate Pinning: The application packages the server's full X.509 certificate. If the server certificate changes or expires, the application must be updated.
• Public Key (SPKI) Pinning: The application stores the cryptographic hash of the server's Subject Public Key Info. This allows server certificates to be renewed without breaking application functionality, provided the underlying private/public key pair remains the same.

Key Implementation Considerations

• Certificate Expiration: Hardcoded certificates require strict update cycles and fallback pins to prevent app breakage upon certificate renewal.
• Interceptors and Middlewares: When writing custom adapters, ensure standard Axios features like request/response interceptors, header transformations, and timeout handling remain properly mapped.
• Error Handling: Native pinning failures must be caught and normalized into standard Axios error structures (e.g., ERR_NETWORK or specific TLS validation errors) so standard application logic can respond appropriately.