You hit a partner API, send a well-formed request with a valid token, and still get slapped with a TLS handshake failure. The endpoint isn’t asking for your API key. It’s asking your client to prove who it is with a certificate, before any HTTP request even leaves your machine. That’s mutual TLS, and if you’ve never configured it in a testing tool, it can stall an integration for a day.
This guide walks through setting up client certificates and CA certificates in Apidog so you can test an mTLS-protected API without fighting the handshake. You’ll add a client cert and key for a specific host, attach a CA certificate so self-signed roots stop throwing errors, and send an authenticated request that Apidog signs automatically. If certificate errors are new territory, the primer on SSL certificate verification is worth a read alongside this one. For the protocol itself, the MDN TLS reference is a solid, vendor-neutral explainer.
What mutual TLS is and why some APIs demand it
Regular HTTPS is one-way trust. The server presents a certificate, your client verifies it, and the connection is encrypted. The server has no cryptographic proof of who you are; it relies on a token or API key inside the request for that.
Mutual TLS makes trust go both ways. The server still presents its certificate, but it also asks the client to present one. If your certificate isn’t signed by a certificate authority the server trusts, the handshake fails and the connection never opens. No request body, no headers, nothing gets through.
You’ll run into mutual TLS (mTLS) authentication in places where a leaked bearer token isn’t an acceptable failure mode:
- Banking and payments. Open-banking APIs and card processors often require a client certificate issued to your organization on top of OAuth. The Stripe docs describe this kind of layered credential model for sensitive financial endpoints.
- Internal and service-to-service traffic. Companies running a zero-trust network make services prove identity with certificates instead of trusting the network perimeter.
- B2B partner APIs. A partner may issue you a client certificate during onboarding so only your registered machines can reach their endpoints.
If OAuth is also in play, the two combine cleanly; RFC 8705 formalizes how mutual-TLS binds an OAuth token to a client certificate. The certificate is a network-layer credential, separate from the application-layer auth in your request. That distinction matters in Apidog, and it’s the thing people most often get tangled up in. Certificates handle mTLS. The Authorization tab handles API keys, bearer tokens, OAuth, and Basic auth. You often need both at once, but you configure them in different places.
How Apidog scopes certificates by host
Apidog handles both CA certificates and client certificates, and it configures them globally rather than per request. You set a certificate up once, tie it to a host, and Apidog attaches it automatically on every HTTPS request that matches that host. There’s no per-request toggle to remember and no header to paste.
Two certificate types do two different jobs:
- A client certificate is what you present to prove your identity for mutual TLS authentication. It’s the credential the partner API asks for.
- A CA certificate tells Apidog to trust a certificate authority it doesn’t already know. Point it at your internal root CA and the dreaded
SSL Error: Self signed certificategoes away, because Apidog now trusts endpoints signed by that authority.
The scoping key is the host. Every client certificate is bound to a domain, and Apidog matches the outgoing request’s host against that binding. Get the host right and everything else is automatic. Get it wrong and Apidog quietly sends nothing, because it never found a match.
Set up a client certificate for an mTLS API
Here’s the scenario. A payments partner, partner-api.acmebank.com, issued you a client certificate and private key during onboarding. Their API is HTTPS only and rejects any client that can’t present that certificate. You want to call GET /v1/settlements and inspect the response.
Step 1: Open the Certificates settings
Open Apidog settings using the settings icon in the top right, then go to the Certificates tab. This is where both certificate types live. Nothing here is tied to a single request; it applies across your requests based on host matching.
Step 2: Add the client certificate
Under Client Certificates, select Add Certificate. A form opens for the host binding and the certificate files.
Fill in the Host field with the domain only, no protocol:
partner-api.acmebank.com
Leave off https://. The field takes a bare domain. If you need one certificate to cover several subdomains, the host field supports pattern matching. Entering *.acmebank.com uses the same client certificate for every subdomain under acmebank.com, which is handy when a partner runs partner-api, sandbox-api, and settlements-api off the same issued cert.
Custom port is optional. Leave it blank and Apidog defaults to 443, the standard HTTPS port. Only set a port if the mTLS endpoint listens somewhere else, say 8443.
Step 3: Select the certificate files
Apidog accepts two file layouts for a client certificate. Pick whichever your partner gave you:
- CRT + Key files. A separate certificate file and private key file. Select each one in its field.
- PFX files. A single bundled file that packs the certificate and key together.
If the certificate was generated with a passphrase, enter it in the passphrase field. It’s optional, so leave it empty if your key isn’t password-protected. A typical onboarding bundle from a bank ships as a .crt and a .key pair, sometimes with a passphrase on the key.
Step 4: Save it
Select Add to save the client certificate. It now appears in your list, bound to partner-api.acmebank.com. From this point on you don’t touch it again per request.
Step 5: Send the authenticated request
Create a request to the host and send it:
GET https://partner-api.acmebank.com/v1/settlements
Authorization: Bearer <your_oauth_token>
Apidog matches the host, attaches your client certificate during the TLS handshake, and completes mutual TLS authentication before the request goes out. If the partner also requires OAuth, that bearer token rides in the request as usual. The certificate proves the machine; the token proves the caller. A successful response might look like this:
{
"settlements": [
{
"id": "stl_88213",
"amount": 41200,
"currency": "USD",
"status": "cleared",
"settled_at": "2026-07-14T09:31:00Z"
}
],
"next_cursor": null
}
No manual per-request step made that happen. The host match did.
Add a CA certificate for internal or self-signed roots
Client certificates are half the story. The other half shows up when the server’s own certificate is signed by an authority your machine doesn’t trust, common with internal services and staging environments that use a private root CA.
When that happens, the request fails with a message like SSL Error: Self signed certificate before mTLS even gets a chance. The fix is to hand Apidog the CA so it trusts that root.
In the same Certificates tab, turn on the toggle next to CA Certificates, then select your PEM file. CA certificates use the PEM format, and a single PEM file can hold multiple CA certificates, so you can bundle a whole chain of internal roots and intermediates into one file:
-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEAgAAuTANBgkqhkiG9w0BAQUFADBaMQswCQYDVQQG...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIEFTCCAv2gAwIBAgIQeM8V5x8B3QksZ4 b2VqkJTANBgkqhkiG9w0BAQ...
-----END CERTIFICATE-----
Once the CA is trusted, Apidog stops rejecting endpoints signed by it. Pair a trusted CA with a client certificate and you can test an internal mTLS service that uses a private root end to end: the CA lets you trust their server, and the client cert lets them trust you.
Advanced tips and common variations
A few things save time once you’re past the basic setup.
Subdomain coverage with one certificate. If a partner issued a wildcard-scoped certificate, set the host to *.acmebank.com once instead of registering partner-api, sandbox-api, and the rest separately. One binding, every subdomain.
Non-standard ports. Internal mTLS gateways love ports like 8443 or 9443. The default is 443, so specify the custom port whenever the endpoint listens elsewhere, or the host won’t match and no certificate gets sent.
Certificates aren’t editable after adding. There’s no edit action. To rotate a renewed certificate or fix a typo in the host, remove the existing one with the delete icon and add it again. Build that into your cert-rotation runbook so nobody hunts for an edit button that isn’t there.
One certificate per domain. Don’t register two client certificates for the same domain. Each binding is domain-specific, and a duplicate creates ambiguity about which one Apidog should present. Keep it to one per host.
Keep certificates and Authorization separate in your head. This is the biggest source of confusion. mTLS lives in the Certificates tab. API keys, bearer tokens, OAuth, and Basic auth live in the Authorization tab of a request or folder, and requests inherit authorization from their parent folder. Authorization applies at three levels: individual requests, all requests in a folder, and all requests in a collection. If a partner needs both a client certificate and OAuth, you set the cert in Certificates and the token in Authorization. They don’t overlap. For a deeper look at wiring up token-based auth, the API gateway authentication guide covers the request side, and if you’re dealing with a Windows-heavy stack, configuring Kerberos authentication in Apidog is a sibling walkthrough worth bookmarking.
HTTPS only, always. Apidog will not attach a client certificate to a plain HTTP request. If your test target is http://, the certificate is never sent and the handshake logic never runs. The endpoint must be HTTPS for any of this to apply.
Automate the workflow with the Apidog CLI
Once your mTLS requests pass by hand, fold them into saved test scenarios and run them headlessly with the Apidog CLI. Install it and authenticate:
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Then run a saved scenario against an environment:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
The apidog run command supports client-certificate configuration directly, so mTLS survives the jump from GUI to pipeline. For a single certificate, pass --ssl-client-cert (the PEM cert), --ssl-client-key (the private key), and --ssl-client-passphrase if the key has one. Point --ssl-extra-ca-certs at additional trusted CAs, or use --ssl-client-cert-list with a config file when you match certificates to hosts by URL pattern. Reporters are set with -r (try -r html,cli). Wire that command into a job and your certificate-protected API gets tested on every push. The Apidog CLI in CI/CD guide covers running it inside a pipeline.
Frequently asked questions
Do I need a client certificate and a CA certificate, or just one?
Depends on the endpoint. A client certificate proves your identity, so you need it whenever the server demands mutual TLS. A CA certificate is only needed when the server’s own certificate is signed by an authority your machine doesn’t already trust, such as an internal root CA. A public partner API on a trusted public CA needs only the client certificate; an internal mTLS service on a private root usually needs both.
Why isn’t Apidog sending my client certificate?
Almost always a host mismatch or a plain HTTP target. Check that the Host field holds the exact domain with no https:// prefix, that the port matches (default 443, so set a custom port if the endpoint listens elsewhere), and that the request URL is HTTPS. Apidog never attaches a certificate to an HTTP request.
Where do API keys and bearer tokens go if not in Certificates?
In the Authorization tab of the request or folder, which is separate from certificate setup. Certificates handle the TLS-layer identity; Authorization handles API Key, Bearer Token, OAuth, and Basic auth at the request layer. You can find the full breakdown of auth types in the security schemes guide, and you can set auth once at the folder or collection level so every request inherits it.
Can one certificate cover multiple subdomains?
Yes. The host field supports pattern matching. Enter *.example.com and the same client certificate applies to every subdomain of example.com. That’s the clean way to reuse a wildcard-scoped certificate a partner issued for several of their API subdomains.
How do I update a certificate after it’s added?
Certificates aren’t editable in place. Remove the existing one with the delete icon, then add the corrected or renewed version. Keep that in mind for certificate rotation, and while you’re organizing test setups, setting global parameters in Apidog pairs well for keeping environment values tidy across requests.
Wrapping up
Testing an mTLS-protected API comes down to three moves in Apidog: bind a client certificate to the right host, attach a CA certificate if the server uses a private root, and let host matching sign every HTTPS request automatically. Keep certificates and Authorization in their separate lanes and the handshake stops being a mystery.
Download Apidog to follow along, add your partner’s certificate, and send that first authenticated request. Try it free, no credit card required.
