Certificate pinning and rotation: how to renew without breaking your apps
Pinned certificates turn a routine renewal into an outage for mobile apps and API clients. How to pin the public key, plan backup pins and rotate safely.
· 7 min read · By the Spot Downtime team
Certificate pinning means a client only trusts a server if its certificate (or key) matches a value built into the client. It blocks attackers who hold a fraudulent but otherwise valid certificate. It also means that a normal certificate renewal can break every installed copy of your mobile app at once, because the new certificate no longer matches the pin.
This post covers what to pin, how to compute the pin, and how to rotate certificates without locking out clients you can't update.
What pinning actually pins
You can pin at three levels, from most to least fragile:
- The leaf certificate. Breaks on every renewal, since each renewal produces a new certificate. Avoid it.
- The public key (SPKI) of the leaf. Survives renewal as long as you reuse the same key pair. Breaks when you generate a new key.
- The public key of an intermediate or root CA. Survives key changes on your side, but trusts everything that CA signs, and breaks if your CA changes its intermediate or you switch CAs.
Pinning the SPKI hash is the common compromise. It is what libraries such as OkHttp's CertificatePinner and Android's network security config expect, in the form sha256/BASE64.
Compute an SPKI pin
For a live server, fetch the certificate, extract the public key and hash it:
openssl s_client -connect api.example.com:443 -servername api.example.com </dev/null 2>/dev/null \
| openssl x509 -pubkey -noout \
| openssl pkey -pubin -outform der \
| openssl dgst -sha256 -binary \
| openssl enc -base64The output, something like 47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=, is your pin. To compute it from a private key you haven't deployed yet, which you need for a backup pin:
openssl pkey -in backup.key -pubout -outform der \
| openssl dgst -sha256 -binary \
| openssl enc -base64Why a backup pin is not optional
If you pin only the current key and that key is lost, compromised or revoked, you can't issue a certificate that clients accept. The only fix is shipping an app update, and users on old versions stay locked out until they upgrade.
Always ship at least two pins: the current key and a backup key pair generated in advance and stored offline. Android's network security config makes this explicit:
<network-security-config>
<domain-config>
<domain includeSubdomains="true">api.example.com</domain>
<pin-set expiration="2027-06-30">
<pin digest="SHA-256">CURRENT_KEY_PIN_BASE64=</pin>
<pin digest="SHA-256">BACKUP_KEY_PIN_BASE64=</pin>
</pin-set>
</domain-config>
</network-security-config>The expiration attribute is a safety valve: after that date, Android stops enforcing the pins rather than blocking all connections. Set it, and keep shipping app releases so users are never close to it.
Rotate in three stages
- Add the new pin to the app first. Release an app version that pins both the current key and the next one. Wait until most users have updated. Check your analytics for the version spread; old versions take months to fade.
- Switch the server to the new key. Issue the certificate with the new key pair and deploy it. Clients that carry both pins keep working. Old clients that only know the old pin will fail, so this step has to wait for the first.
- Remove the old pin and add the next backup. In a later release, drop the retired key and add a fresh backup.
The easy case: renew with the same key
certbot renew --reuse-key (or --reuse-key on certonly) keeps the same private key across renewals, so an SPKI pin stays valid. Rotate keys on a planned schedule, not by accident on every renewal. Automated clients such as ACME agents generate new keys by default.Symptoms when a pin breaks
Pinning failures look like network failures. The app shows a generic error, and the server sees nothing, because the TLS handshake is aborted by the client. The server logs stay quiet while users report that the app "can't connect". A browser or curl against the same host works fine, which makes it look like the problem is in the app.
- OkHttp throws
SSLPeerUnverifiedException: Certificate pinning failure!and prints the pins it saw. The list is useful: it shows the real pin. - On iOS, URLSession fails with
NSURLErrorServerCertificateUntrustedor a cancelled authentication challenge. - Node and Python clients using a custom check raise a fingerprint or hostname mismatch error.
If the failure started right after a deploy or renewal, compare the pin the server now presents with the pins in the app. A new CA intermediate is another trigger: CAs rotate intermediates, and a pin to the intermediate stops matching. For the general trust-chain errors, see ERR_CERT_AUTHORITY_INVALID and incomplete certificate chains.
What about HPKP and browsers?
Browsers had their own pinning mechanism, HTTP Public Key Pinning, and it is gone. It was removed from Chrome and Firefox because a mistake could lock visitors out of a site for months and attackers could abuse it. Don't send Public-Key-Pins headers. For websites, use HSTS, CAA records (see DNS CAA records) and certificate transparency monitoring instead. Pinning today belongs in apps and API clients you control.
Check what your server presents
Before and after any rotation, verify that the certificate and chain your server sends are what you expect. A load balancer that still serves the old certificate on one node causes intermittent pinning failures that only some users see.
SSL checkerSee the certificate, chain and expiry date a domain presents right now.TLS checkerCheck supported TLS versions and what the handshake negotiates.Monitor the endpoint the app actually uses
Pinning problems are invisible to the server, so watch from the outside. A certificate monitor in Spot Downtime warns before the certificate expires, which gives you time to rotate on your schedule rather than in an emergency. See SSL expiry alert lead times for how far ahead to set warnings, and how to monitor SSL and domain expiry for setup. Add an API monitor on the pinned hostname as well, so an expired or misconfigured certificate shows up as a failed check immediately.
Get new guides by email
Practical posts on monitoring, outages, error fixes and on-call, when they're published. No spam.
Keep reading
- SSL · TroubleshootingHSTS explained: how to enable it, and how to undo it when it locks you outWhat the Strict-Transport-Security header does, how to roll it out safely, why browsers show an error with no bypass button, and how to remove HSTS or the preload list.November 7, 2026 · 7 min read
- SSL · DNS · TroubleshootingCAA records: why your certificate won't issue (and how to fix it)A CAA record tells certificate authorities which of them may issue for your domain. Learn the syntax, how to debug CAA failures from Let's Encrypt and others, and how to fix them.November 3, 2026 · 6 min read