> ## Documentation Index
> Fetch the complete documentation index at: https://docs.requestly.com/llms.txt
> Use this file to discover all available pages before exploring further.
# SSL Certificates
> Add custom CA certificates and per-host client certificates to authenticate against internal or mTLS-protected APIs in the Requestly desktop app.
Many internal APIs use a private certificate authority (CA) instead of a public one, or require a client certificate to prove the caller's identity (mutual TLS / mTLS). Requestly lets you add both kinds of certificate from App Settings so every request to the right host automatically picks them up, with no changes needed to individual requests or collections.
Certificates stay on this device. They are not synced to the Requestly cloud, so each device must add its own copy.
These settings apply across every request type the API client sends: REST/HTTP, GraphQL queries and mutations, and GraphQL subscriptions over WebSocket (`wss://`). The same CA trust set and client-certificate matching rules apply uniformly.
## Prerequisites
* Requestly desktop app version 2605.12.2 or later.
* For CA certificates: a PEM-encoded CA certificate file (`.pem` or `.crt`).
* For client certificates: either a PEM pair (certificate file `.crt` / `.pem` + private key file `.key`) or a PFX bundle (`.pfx` / `.p12`). Optional passphrase if the key or bundle is encrypted.
## Open the Certificates settings
Click the **Settings** icon in the application footer, or navigate to **App Settings** from the menu.
Scroll to the **Certificates** section. It contains two panels: **CA Certificate** and **Client Certificates**.
## CA certificates
A CA certificate tells Requestly to trust servers whose certificate chain is signed by that CA. Use it when your internal API returns a certificate signed by your company's own CA and requests fail with an SSL error.
Requestly merges your uploaded CA with the system and Node built-in trust roots, so public HTTPS sites continue to work normally. You do not need to replace the default trust set.
### Add a CA certificate
In the **CA Certificate** section, click **Add CA Certificate**. An OS file picker opens.
Choose your PEM-encoded CA certificate file (`.pem` or `.crt`). The certificate appears in the list and is enabled by default.
Only one CA certificate is supported at a time. The **Add CA Certificate** button stays disabled while a certificate is already listed, so delete the existing one before switching to a different CA.
### Enable or disable a CA certificate
Each CA certificate row has an **Enabled** toggle. Turn it off to stop trusting that CA without deleting the certificate.
Toggle the CA off to quickly check whether it is the cause of a trust error, without losing your reference to the certificate file.
### Delete a CA certificate
Click the delete icon on the row. A confirmation dialog explains that the cert file on disk is not deleted, only the reference inside Requestly is removed.
## Client certificates
A client certificate lets Requestly prove the caller's identity during a TLS handshake. The certificate is attached only to requests whose host and port match the rule you configure.
### Add a client certificate
In the **Client Certificates** section, click **Add Client Certificate**.
Enter a specific hostname (`api.internal.example.com`) or a single-label wildcard (`*.example.com`) in the **Host** field.
The wildcard matches one subdomain level only: `*.example.com` matches `api.example.com` but not `a.api.example.com` and not `example.com` itself.
The default is 443. Change it if your API runs on a non-standard port.
Pick the format that matches your certificate bundle:
* **Certificate (PEM)**: select your certificate file and your private key file separately.
* **PFX**: select a single `.pfx` or `.p12` bundle that contains both.
If the key or bundle is protected by a passphrase, enter it in the **Passphrase** field. The passphrase is stored encrypted at rest on this device.
Switch to the **PFX** tab if you have a single bundle file instead:
Click **Add**. The new rule appears in the Client Certificates list.
Only one client certificate rule is allowed per host-and-port pair. If a rule already exists for the same host and port, Requestly asks you to confirm before replacing it.
### Delete a client certificate
Click the delete icon on the row. The confirmation dialog shows the host and port the rule covered. As with CA certificates, the cert files on disk are not deleted.
Client certificate rows do not have an individual enable toggle. To stop attaching a certificate to a host, delete the row.
## How certificate matching works
When you send a request, Requestly checks the request URL against your client certificate rules in this order:
1. Exact host match (case-insensitive) takes priority over wildcard matches.
2. Ports must match exactly. If the URL has no explicit port and uses `https`, port 443 is assumed.
3. The first matching rule is used. At most one client certificate is attached per request.
If no rule matches, no client certificate is sent.
CA certificates that are enabled are always merged in for every HTTPS request. Disabled CA certificates are ignored.
## TLS errors in the response panel
When a request fails because of a TLS or certificate problem, the response panel shows an **SSL Error** message describing what went wrong (for example, `SSL Error: UNABLE_TO_VERIFY_LEAF_SIGNATURE`). A **Manage certificates** button appears next to the error to jump directly to the Certificates settings.
Common errors and what they usually mean:
| Error code | Likely cause |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `UNABLE_TO_VERIFY_LEAF_SIGNATURE` | The server's certificate chain is incomplete or signed by a CA Requestly does not trust. Add the CA certificate. |
| `ERR_TLS_CERT_ALTNAME_INVALID` | The hostname in the request does not match any name on the server's certificate. Check that the URL is correct. |
| `CERT_HAS_EXPIRED` | The server's certificate has passed its expiry date. This is a server-side issue. |
| `ERR_SSL_WRONG_VERSION_NUMBER` | TLS version mismatch between Requestly and the server. |
If a cert file referenced in your settings cannot be read from disk (for example, the file was moved), the error reads `SSL Error: Certificate file not found` and includes the path. Re-add the certificate from its new location to fix it.
## Inspect TLS details after a successful request
For HTTPS requests that succeed, you can see the full handshake details in DevTools.
Click **DevTools** in the application footer.
Go to the **Network** tab and click the request whose TLS details you want to inspect.
Select the **Info** tab in the detail panel. It shows the TLS version, cipher suite, server certificate (subject, issuer, and expiry date), and, when a client certificate was sent, the matched rule (host pattern and port), the certificate subject, and the SHA-256 fingerprint.
## What's Next
Set API keys, Bearer tokens, and other auth schemes on requests or collections
Inspect TLS handshake details, headers, and script logs in one panel