@capgo/capacitor-ssl-pinning

Add SSL certificate pinning to your Capacitor app's native HTTP requests on iOS and Android, so your API traffic only trusts your own certificates.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-ssl-pinning in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-ssl-pinning to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Config only: list certificate files under plugins.SSLPinning.certs in capacitor.config.
• CapacitorHttp: pinning applies to CapacitorHttp requests when it is enabled and at least one certificate is listed.
• Sync hook: cap sync copies the certificates and converts PEM files to DER for iOS.
• Exclusions: excludedDomains lets chosen URLs skip pinning.
• Inspect: getConfiguration() returns the active native configuration.
• Platforms: iOS and Android. Not available on web.

Capgo SSL Pinning brings certificate pinning to Capacitor 8 apps by integrating with CapacitorHttp on Android and iOS.

The implementation follows the Ionic SSL pinning install flow and uses the same plugins.SSLPinning configuration shape documented at ionic.io.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/ssl-pinning/

Compatibility

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-ssl-pinning` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

bun add @capgo/capacitor-ssl-pinning
bunx cap sync

Configure

Enable Capacitor HTTP interception and declare the certificate files relative to your app root:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    CapacitorHttp: {
      enabled: true,
    },
    SSLPinning: {
      certs: ['sslCerts/production/primary.cer', 'sslCerts/production/backup.der'],
      excludedDomains: ['https://analytics.google.com'],
    },
  },
};

export default config;

During bunx cap sync, the plugin copies the configured certificates into webDir/certs, which lets both native implementations load them from the bundled app assets. Both .cer and .der are supported; PEM .cer files are converted to DER automatically for iOS.

Usage

Make HTTPS calls with CapacitorHttp:

import { CapacitorHttp } from '@capacitor/core';

const response = await CapacitorHttp.get({
  url: 'https://api.example.com/health',
});

If the server certificate does not match one of the pinned certificates, the native request fails.

Behavior

• Android injects a pinned SSLSocketFactory into Capacitor HTTP requests unless the URL matches excludedDomains.
• iOS swaps the default Capacitor HTTP handler with a pinned URLSession delegate and also answers WebView authentication challenges through the Capacitor plugin hook.
• Web exposes inspection helpers only; browsers do not support this native pinning behavior.

API

• getConfiguration()
• getPluginVersion()
• Interfaces

Capacitor API for inspecting SSL pinning configuration.

Native enforcement is applied automatically to CapacitorHttp requests when:

1. plugins.CapacitorHttp.enabled is true
2. plugins.SSLPinning.certs contains at least one certificate

getConfiguration()

getConfiguration() => Promise<SSLPinningConfigurationState>

Returns the active native configuration visible to the plugin.

Returns: Promise<SSLPinningConfigurationState>

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Returns the native implementation version marker.

Returns: Promise<PluginVersionResult>

Interfaces

SSLPinningConfigurationState

Static SSL pinning configuration currently visible to the plugin.

PluginVersionResult

Plugin version payload.