Skip to main content

Configure certificates and mTLS

This guide is for teams deploying a private hosted agent against APIs that require client-certificate authentication (mTLS), a custom Certificate Authority (CA), or both.


Overview​

The APIsec Private Hosted Agent supports certificate-based reachability and authentication for scan targets that:

  • require mutual TLS (mTLS) — where the API server expects the client (the hosted agent) to present a client certificate;
  • are served by a private Certificate Authority (CA) — where the API server's TLS certificate is signed by a CA that the hosted agent does not trust by default; or
  • require both, which is common in enterprise environments where the gateway terminates TLS with a private CA and also enforces mTLS upstream.

You tell APIsec which certificate file to use for which host from the Hosted Agents page. The certificate files themselves stay on the machine that runs the agent: APIsec only stores the mapping (host, file name and password), never the certificates or their private keys.

note

Managing certificates is available to tenant admins only. Other users do not see the Manage certificates button.

What you need before you start​

ItemNotes
A hosted agent on image apisec/hostedagent:2026-10-27-94 or laterEarlier agent versions ignore the certificates configured in APIsec. They can only use the local configuration file.
The hosted agent's install command from the APIsec dashboard"Download Script" under the Hosted Agents page. You will add one line to it.
A persistent location to hold your certificatesTwo options: (a) a directory on the Docker host (e.g. /opt/apisec/certs on Linux, C:\apisec\certs on Windows) for single-host deployments; OR (b) an AWS EFS-mounted volume for fleet deployments on ECS / EKS where multiple agents share the same certificate set. Certificates must live on persistent storage — manually copying them into the container (docker cp) will not persist a restart.
Your client certificate file (if using mTLS)Supported formats: .pfx or .p12 (PKCS#12, password-protected). PEM client certificates are not supported — see Supported certificate file formats.
The passphrase for the client certificate (if any)Required for the .pfx / .p12 you exported. PKCS#12 client certificates are conventionally password-protected.
Your private CA bundle file (if using a private CA)Supported formats: .pem (the usual format), or PKCS#12 (.pfx / .p12) if your CA was exported in that format.
Knowledge of which target hostname(s) need which certificateThe hostname only — do not include http:// or https://. See How the agent picks a certificate for ports and wildcards.

Step-by-step setup​

Step 1 — Put the certificate files on the agent machine​

Create a directory and copy the certificate files into it.

mkdir -p /opt/apisec/certs
cp client-cert.pfx /opt/apisec/certs/
cp customer-ca.pem /opt/apisec/certs/

Step 2 — Mount the directory into the agent​

Take the install command you downloaded from the APIsec dashboard, find the docker run line and add one line to it:

Line to addPurpose
-v "/opt/apisec/certs:/app/certificates:ro"Mount the certificate directory into the container at the path the agent reads from. The :ro suffix mounts it read-only — recommended, since the agent only reads certificates and never writes them.

Option A — docker run​

docker run -d --name "apisechostedagent-{brokerId}" \
--restart=unless-stopped --cpus=1 --memory=2g \
-v "apisec-agent-data-{brokerId}:/tmp" \
-v "/opt/apisec/certs:/app/certificates:ro" \ # ← ADDED (read-only)
-e MICRONAUT_ENVIRONMENTS=broker \
...
apisec/hostedagent:2026-10-27-94

Keep every other line of the downloaded command as it is.

Option B — docker-compose​

services:
private-agent:
image: apisec/hostedagent:2026-10-27-94
container_name: apisechostedagent-{brokerId}
restart: unless-stopped
volumes:
- apisec-agent-data:/tmp
- /opt/apisec/certs:/app/certificates:ro # ← ADDED (read-only)
environment:
- MICRONAUT_ENVIRONMENTS=broker
# ... the rest of the environment from the downloaded command
volumes:
apisec-agent-data:

Option C — AWS ECS / EKS with EFS​

For fleet deployments where multiple hosted agents must share the same certificate set, mount your certificates from an AWS EFS file system rather than a host directory. In your ECS task definition (or EKS pod spec), add an EFS-backed volume and mount it at /app/certificates inside the agent container. Every agent task then sees the same certificate files.

If the agent is already running, stop and remove it first (docker stop apisechostedagent-{brokerId}, then docker rm apisechostedagent-{brokerId}), then start it with the modified command. You only need to do this once: later certificate changes in APIsec reach the agent without a restart, and new files dropped into the mounted directory are picked up as soon as a scan needs them.

Step 3 — Map hosts to certificates in APIsec​

Open Hosted Agents and click Manage certificates, next to New Hosted Agent.

Manage certificates button on the Hosted Agents page

Click Add certificate for each certificate a host needs, fill in the card, then click Save changes.

Manage certificates dialog with a CA entry for example.org and a client entry for api.example.org

FieldWhat to enter
HostThe target hostname, with a port only if the entry should apply to that port alone. *.example.com covers every subdomain of example.com; * covers every host. No http://, https:// or paths.
CA certificateTick it when the file is a CA the agent should trust for this host. Leave it unticked when the file is a client certificate the agent should present.
File nameThe name of the file in the mounted directory. The extension is added from Type when you leave it out (client with type PFX is saved as client.pfx), and switching the type swaps it (client.p12 changed to PFX becomes client.pfx). The dialog shows the final name under the field. Names are matched ignoring case.
TypeP12 or PFX for client certificates; PEM, P12 or PFX for CA certificates.
PasswordThe file's passphrase. PEM files have no password. A saved password is never shown again; leave it untouched to keep it.

Each host can have one client certificate and one CA certificate. If an entry cannot be saved (for example, a duplicate host, or a host typed as a full URL), its card stays open with the reason and the other changes are still saved.

The entries apply to every hosted agent in your tenant. Running agents reload them within seconds of saving, with no restart.

Step 4 — Check the agent loaded the certificates​

On the Hosted Agents page, expand the agent and open the Certificates tab. Each entry is listed with its type, expiry date and status:

  • Loaded — the file was found and opened with the saved password.
  • Failed — the file is missing from the mounted directory, or the password is wrong.

Agent Certificates tab with a loaded CA certificate and a failed client certificate

The agent reports this status when it starts, after every certificate change, and hourly.


How the agent picks a certificate​

For every request, the agent looks for the best client certificate and, separately, the best CA certificate for the target host:

  1. An entry for the exact host wins.
  2. Otherwise, the most specific *.domain entry that covers the host (*.api.example.com beats *.example.com). A *.example.com entry does not cover the bare example.com.
  3. Otherwise, the * entry, if there is one.

An entry without a port applies to every port of its host; an entry with a port (api.example.com:8443) applies to that port only, and wins over a port-less entry for the same host.

Because client and CA are picked separately, an exact-host client certificate and a *.example.com CA are both used for api.example.com.


When a certificate cannot be loaded​

A certificate problem never makes the agent unhealthy: the agent stays Active, and the entry shows Failed in the Certificates tab. Only scans of the hosts that entry covers are affected. When a scan targets such a host, the agent sends nothing without the certificate and the scan fails with the reason:

Scan failed with the reason that client.pfx configured for api.example.org could not be loaded

Instance Service Reachability Failure. Client certificate client.pfx configured for host api.example.org could not be loaded: /app/certificates/client.pfx (No such file or directory). Check that the file exists in the agent's certificates folder and that the passphrase is correct.

Scans of other hosts on the same agent keep working.

warning

A * entry covers every host. If its file is missing on an agent, every scan through that agent fails — including scans of APIs that need no certificate at all. Prefer exact hosts or *.domain entries, and make sure every agent that may scan a covered host has the files mounted.

To fix a failed entry, place the file in the mounted directory or correct the file name or password in Manage certificates. No restart is needed.


Configuration scenarios​

Scenario A — Customer API requires mTLS only​

The API server requires the agent to present a client certificate. Its own TLS certificate is signed by a well-known public CA.

HostCA certificateFile nameTypePassword
api.customer.example.comuntickedclient-certPFXyour passphrase

Scenario B — Customer API uses a private CA only​

The API server's TLS certificate is signed by an internal CA. The server does not require mTLS.

HostCA certificateFile nameTypePassword
api.customer.example.comtickedcustomer-caPEM—

Scenario C — Customer API requires both mTLS and a private CA​

The most common enterprise case: add both entries for the same host.

HostCA certificateFile nameTypePassword
api.customer.example.comuntickedclient-certPFXyour passphrase
api.customer.example.comtickedcustomer-caPEM—

Scenario D — One CA covers all hosts of a domain​

A single internal root CA signs every API under customer.example.com.

HostCA certificateFile nameTypePassword
*.customer.example.comtickedinternal-root-caPEM—

Scenario E — Mixed: one host needs mTLS, the rest of the domain needs a private CA​

HostCA certificateFile nameTypePassword
api.customer.example.comuntickedclient-certPFXyour passphrase
*.customer.example.comtickedinternal-root-caPEM—

api.customer.example.com gets both: its own client certificate, and the domain CA (no exact-host CA entry exists).


Supported certificate file formats​

FormatExtensionPassphraseNotes
PKCS#12.pfx, .p12Usually requiredThe only format supported for client certificates. Also accepted for CA bundles if your CA was exported this way.
PEM.pemNot usedCA bundles only.

Other formats (.cer, .crt, .der, .jks) are not supported — convert them to one of the formats above before use.


Local configuration file (config.json)​

Before certificates could be managed in APIsec, they were mapped in a config.json file next to the certificate files. Agents still support it, so existing setups keep working unchanged. For new setups, use Manage certificates instead.

Turning the local file on or off​

The ENABLE_CERTIFICATES environment variable decides which configuration the agent uses:

ENABLE_CERTIFICATESCertificates from APIsecLocal config.json
not set (default)UsedIgnored
trueUsedLoaded at startup; any problem with it stops the agent from starting
falseIgnoredIgnored — certificates are turned off entirely

How local and APIsec entries combine​

With ENABLE_CERTIFICATES=true, the agent uses both:

  • For the same host and type (client or CA), the local entry wins and the APIsec entry is ignored. The agent logs Remote ... certificate ignored: the local config.json covers this host.
  • Otherwise, entries from both sources compete under the usual rules: an APIsec entry for api.example.com beats a local *.example.com entry, and the other way round.

Setting it up​

Save config.json at the root of the mounted certificate directory, and add -e ENABLE_CERTIFICATES=true to the docker run command next to the volume mount.

[
{
"host": "api.customer.example.com",
"filename": "client-cert.pfx",
"passphrase": "your-cert-passphrase",
"caFilename": "customer-ca.pem"
},
{
"host": "*",
"caFilename": "internal-root-ca.pem"
}
]

Unlike APIsec entries, one config.json entry holds both the client certificate and the CA for a host:

FieldTypeRequiredDescription
hoststringYesTarget hostname, same rules as the Host field above (*.domain and * wildcards, optional port, no scheme or path).
filenamestringConditionalThe client-certificate file name (.pfx / .p12), including the extension.
passphrasestringConditionalPassphrase for the client certificate.
caFilenamestringConditionalThe CA file name (.pem, .pfx or .p12), including the extension.
caPassphrasestringConditionalPassphrase for the CA file. Usually empty (most CA bundles are plain PEM).

Each entry must have at least one of filename or caFilename.

The local file is read once, at startup: after changing config.json or a file it references, restart the agent (docker restart apisechostedagent-{brokerId}). Passphrases in config.json are plain text, so restrict access to the directory (chmod 600 config.json) as you would any other secret.

Startup failures​

With ENABLE_CERTIFICATES=true, the agent checks the whole config.json while it starts. Any problem stops startup, and the container's restart policy brings it back, so it loops until you fix the issue. Read the reason from the logs:

docker logs apisechostedagent-{brokerId} | grep certificate-manager

docker logs returns the output from the most recent start attempt even after the container has exited.

Log messageFix
Certificates directory not found at '/app/certificates/'The volume mount is missing or points at the wrong host path.
Certificate configuration file not found at '/app/certificates/config.json'config.json must be at the root of the mounted directory, not in a subdirectory.
Failed to parse certificate configuration file '...'Invalid JSON — check for trailing commas, missing quotes or a wrong file encoding.
Could not load certificate [<file>]. Error: keystore password was incorrectWrong passphrase, or a corrupted PKCS#12 file.
Certificate [<file>] not foundPlace the file in the directory, or correct the file name in config.json.
PEM is not supported in the client-certificate slot [<file>]Convert the client certificate to .pfx / .p12; keep .pem for caFilename.
Only .pfx, .p12 and .pem certificates are supportedConvert files with any other extension.
Could not load PEM certificate [<file>]. Error: ...The CA .pem file is unreadable — check its contents and encoding.
No certificate specified for host: <host>The entry needs a filename, a caFilename, or both.
No host specified for certificateAdd a host value to the entry.
Hostname should not start with 'http://' or 'https://'Use a bare hostname in host.

A successful start logs:

[certificate-manager] mTLS certificate manager initialized. Enabled: true
[certificate-manager] [host: api.customer.example.com] Validating certificate configuration.
[certificate-manager] [host: api.customer.example.com] Loaded client certificate: client-cert.pfx
[certificate-manager] Successfully loaded 1 certificate configuration(s).
note

CERTIFICATES_BASE_PATH (default /app/certificates/) sets the directory inside the container where the agent looks for certificate files and config.json. It must end with a trailing slash; override it only if you mount the directory somewhere else.


Troubleshooting​

SymptomLikely causeFix
Entry shows Failed in the agent's Certificates tabThe file is not in the mounted directory, the file name is wrong, or the password is wrongCheck the volume mount and the file name (shown as "Saved as …" in Manage certificates); re-enter the password.
Every scan through an agent fails with "could not be loaded"A * entry whose file is missing on that agentMount the file on that agent, or replace * with exact hosts or *.domain entries.
Scan of a host fails with TLS handshake errors although an entry existsThe entry does not cover the host the agent connects to — a typo, a bare domain under a *.domain entry, or an entry with a different portCompare the entry's host with the instance URL.
The Certificates tab shows no entriesThe agent runs an image older than 2026-10-27-94, or has ENABLE_CERTIFICATES=falseUpgrade the agent image; remove ENABLE_CERTIFICATES=false.
A change in Manage certificates is not used by an agent with ENABLE_CERTIFICATES=trueconfig.json has an entry for the same host and type, and local entries winChange or remove the local entry, then restart the agent.

Frequently Asked Questions​

Q. Can I add or change certificates without restarting the agent?​

Yes, for certificates managed in APIsec: agents reload them within seconds of saving, and new files in the mounted directory are used as soon as a scan needs them. Changes to a local config.json still need a restart.

Q. Can I combine a client certificate with a Bearer Token or API Key?​

Yes. The client certificate is used for the TLS handshake (mTLS), and the Bearer Token / API Key is sent in the request Authorization header. Configure the token under the application's authentication profile as usual; the agent presents the matching certificate for the target host AND injects the token header.

Q. I have several hosted agents. Which ones need the certificate files?​

Certificate entries apply to every hosted agent in the tenant, so every agent that may scan a covered host needs the files mounted. An agent without them fails those scans with the "could not be loaded" reason; it does not retry through a different agent. If only some agents have the files, set one of them as the instance's preferred agent.

Q. Will the certificates persist across container restarts and re-deploys?​

The mapping lives in APIsec, so it always survives. The files survive only if mounted via a Docker volume or an EFS-mounted volume as described above — files copied into a running container with docker cp are lost when it stops.

Q. Where can I see the certificates the agent has loaded and when they expire?​

In the APIsec dashboard, open the Hosted Agents page, expand the agent, and select the Certificates tab. It shows each entry's expiry date and whether it loaded.

Q. What happens if a certificate expires while the agent is running?​

The agent keeps using the certificate until the API server rejects it. Rotate certificates before their expiration date — the Certificates tab shows the expiry date and alerts when a certificate is approaching it. To rotate, replace the file in the mounted directory (and update the password in Manage certificates if it changed).

Q. Are passphrases stored securely?​

Passphrases entered in Manage certificates are stored encrypted, sent to agents encrypted, and never shown again in the dashboard. Passphrases in a local config.json are plain text on the agent machine — restrict access to that directory.

Q. Does the certificate manager work for both Linux and Windows hosted-agent containers?​

Yes. The only difference is the host-path syntax in the volume mount (/opt/apisec/certs on Linux, C:\apisec\certs on Windows).

Q. Does this affect the agent's outbound connection to the APIsec SaaS platform?​

No. Certificate configuration applies only to the agent's connections to your scan targets. The agent's own connection to APIsec uses the platform's standard TLS.

Q. What if my target host has a wildcard certificate (e.g. *.customer.com)?​

The Host field matches the hostname the agent connects to, not the server certificate's Common Name or SAN. To cover every subdomain with one entry, use *.customer.com as the host (it does not cover customer.com itself).


Support​

If certificate configuration is failing and the messages above do not point to a clear fix, contact your APIsec Customer Success representative with:

  1. The output of docker logs apisechostedagent-{brokerId} | grep certificate-manager
  2. A screenshot of the agent's Certificates tab
  3. The Docker inspect output for the container (docker inspect apisechostedagent-{brokerId} | grep -A2 Mounts) to confirm the volume mount is correct
  4. If you use a local config.json, a redacted copy — replace passphrases with *** before sharing