How to Configure CA and Client Certificates in Bruno

When an API uses HTTPS, certificates help establish trust before any request data is exchanged. A CA certificate helps Bruno verify that the server is genuine. A client certificate works in the other direction: it lets the server verify the identity of Bruno or the application making the request. When both checks happen in the same connection, the result is called mutual TLS (mTLS).

This beginner-friendly guide explains what CA and client certificates do, what happens during TLS and mTLS handshakes, and how to configure both in Bruno. At the end, you can fetch a ready-made sample collection and test the complete flow against badssl.com.

Certificates in API Development

A digital certificate is an electronic identity document. It contains information such as a domain or identity, a public key, an issuer, and an expiry date. A trusted Certificate Authority digitally signs the certificate so that another system can verify that it has not been forged or modified.

In an API connection there can be two separate identity checks:

What Is a CA Certificate?

A Certificate Authority (CA) is an organization or internal system that signs certificates. Your operating system and applications already trust a set of well-known public CAs. That is why Bruno can normally connect to public HTTPS APIs without additional setup.

Private company APIs often use certificates signed by an internal CA. Because that CA is not in the normal public trust store, Bruno cannot verify the server and the request fails with an error such as self-signed certificate, unable to verify the first certificate, or unable to get local issuer certificate.

Adding the internal CA certificate tells Bruno: “Certificates signed by this authority may be trusted, provided the certificate is valid and matches the requested host.” You are adding a trusted issuer—not bypassing certificate verification.

What Is a Client Certificate?

A client certificate identifies the client to the server. APIs commonly use it for banking, payment systems, B2B integrations, internal services, healthcare systems, and zero-trust networks.

The server asks for a certificate during the TLS handshake. Bruno presents the certificate configured for that server’s domain and proves that it owns the associated private key. The private key itself is never sent over the network.

How TLS and mTLS Handshakes Work

The handshake happens before Bruno sends the HTTP, gRPC, or WebSocket request. It creates an encrypted channel and determines which identities must be verified.

Normal TLS: Bruno verifies the server

Mutual TLS: both sides verify identity

TLS protects data in transit. mTLS adds strong client authentication at the connection layer. Your API may still require a bearer token, API key, or another application-level credential after mTLS succeeds.

How to Configure a CA Certificate in Bruno

Use a custom CA when the server certificate was signed by an internal or otherwise untrusted authority.

How to Configure Client Certificates in Bruno

Bruno supports client certificates for HTTPS, gRPC, and WebSocket requests. From Bruno v4.1.0, you can configure certificates globally or for one collection.

Option A: Add a global client certificate

Option B: Add a collection client certificate

Temporarily disabling a certificate

Each global and collection certificate has its own enable/disable switch and is enabled by default. Disable an entry when you want to test another certificate or debug a configuration without deleting it. Disabled entries are skipped completely during certificate resolution.

Certificate Matching and Precedence

Bruno selects a client certificate by matching the request host against each configured domain. Only enabled entries are considered, and matching uses first-match behavior.

If both levels contain an enabled certificate for the same domain, the collection certificate wins. This lets a collection override a reusable global default.

Using Client Certificates with Bruno CLI

The CLI does not read global certificates from the desktop Preferences store. For local terminal runs or CI, pass an additional certificate file using --client-cert-config.

# run from inside the collection directory
cd /path/to/your-collection

bru run --client-cert-config /path/to/client-cert-config.json

# run only the payments folder, still inside the collection
bru run payments --client-cert-config /path/to/client-cert-config.json

Example configuration:

{
  "enabled": true,
  "certs": [
    {
      "domain": "*.internal.example.com",
      "type": "cert",
      "certFilePath": "/abs/path/client.crt",
      "keyFilePath": "/abs/path/client.key",
      "passphrase": ""
    },
    {
      "domain": "payments.example.com",
      "type": "pfx",
      "pfxFilePath": "/abs/path/payments-client.pfx",
      "passphrase": "use-a-secure-value"
    }
  ]
}

• The JSON file must exist and contain valid JSON.
• The top-level enabled field must be true.
• Collection certificates are loaded first.
• Certificates from --client-cert-config are appended after them.
• For overlapping domains, the collection certificate therefore wins.
• Collection certificates marked disabled are skipped.

Try It with a Sample Collection

The client-cert-badssl sample collection includes two requests:

Troubleshooting

Wrap Up

The easiest way to remember the difference is direction: a CA certificate helps Bruno trust the server, while a client certificate helps the server trust Bruno. Standard TLS normally performs the first check. mTLS performs both.

In Bruno, add a private CA under Preferences → General. Add reusable client certificates under Preferences → Client Certificates, or configure a collection-level certificate when the files and settings belong to one collection. Leave certificate verification enabled, protect private keys, and use the CLI configuration flag in CI because the CLI does not read desktop Preferences.