> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/agentgateway/agentgateway/llms.txt
> Use this file to discover all available pages before exploring further.

# TLS

> Reference for TLS configuration — listener TLS termination and backend TLS origination.

Agentgateway supports TLS in two directions:

* **Listener TLS** (`tls`) — TLS termination on the inbound listener. Clients connect over HTTPS/TLS.
* **Backend TLS** (`backendTLS`) — TLS origination when connecting to upstream backends. Agentgateway establishes encrypted connections to backends.

Only TLS **1.2** and **1.3** are supported.

## Listener TLS

Listener TLS is configured on `binds[].listeners[]`:

```yaml theme={null}
binds:
- port: 3000
  listeners:
  - name: default
    protocol: HTTPS
    tls:
      cert: examples/tls/certs/cert.pem
      key: examples/tls/certs/key.pem
```

<ParamField body="tls" type="object">
  TLS configuration for the listener.

  <Expandable title="tls fields">
    <ParamField body="tls.cert" type="string" required>
      Path to the PEM-encoded TLS certificate file. The path is relative to the directory from which the Agentgateway binary runs.

      ```yaml theme={null}
      tls:
        cert: examples/tls/certs/cert.pem
      ```
    </ParamField>

    <ParamField body="tls.key" type="string" required>
      Path to the PEM-encoded private key file.

      ```yaml theme={null}
      tls:
        key: examples/tls/certs/key.pem
      ```
    </ParamField>

    <ParamField body="tls.root" type="string">
      Path to the PEM-encoded CA certificate bundle used for client certificate verification (mTLS). When set, Agentgateway requests and validates client certificates.

      ```yaml theme={null}
      tls:
        root: examples/tls/certs/ca.pem
      ```
    </ParamField>

    <ParamField body="tls.cipherSuites" type="string[]">
      Optional allowlist of TLS cipher suites. The order in which ciphers are listed is preserved. When omitted, the default cipher suite selection applies.

      ```yaml theme={null}
      tls:
        cipherSuites:
        - TLS_AES_128_GCM_SHA256
        - TLS_AES_256_GCM_SHA384
      ```
    </ParamField>

    <ParamField body="tls.minTLSVersion" type="string">
      Minimum TLS version to accept. Only `1.2` and `1.3` are supported.

      ```yaml theme={null}
      tls:
        minTLSVersion: "1.2"
      ```
    </ParamField>

    <ParamField body="tls.maxTLSVersion" type="string">
      Maximum TLS version to accept. Only `1.2` and `1.3` are supported.

      ```yaml theme={null}
      tls:
        maxTLSVersion: "1.3"
      ```
    </ParamField>
  </Expandable>
</ParamField>

## Backend TLS

Backend TLS is configured under `binds[].listeners[].routes[].policies`:

```yaml theme={null}
binds:
- port: 3000
  listeners:
  - routes:
    - policies:
        backendTLS:
          hostname: backend.example.com
          root: /etc/ssl/certs/ca-certificates.crt
```

<ParamField body="backendTLS" type="object">
  TLS configuration for connections to upstream backends.

  <Expandable title="backendTLS fields">
    <ParamField body="backendTLS.cert" type="string">
      Path to the PEM-encoded client certificate file used for mutual TLS (mTLS) with the backend.

      ```yaml theme={null}
      backendTLS:
        cert: /etc/ssl/client.crt
      ```
    </ParamField>

    <ParamField body="backendTLS.key" type="string">
      Path to the PEM-encoded private key for the client certificate.

      ```yaml theme={null}
      backendTLS:
        key: /etc/ssl/client.key
      ```
    </ParamField>

    <ParamField body="backendTLS.root" type="string">
      Path to the PEM-encoded CA certificate bundle used to verify the backend's certificate.

      ```yaml theme={null}
      backendTLS:
        root: /etc/ssl/certs/ca-certificates.crt
      ```
    </ParamField>

    <ParamField body="backendTLS.hostname" type="string">
      Override the Server Name Indication (SNI) hostname sent to the backend. When omitted, the backend's hostname is used.

      ```yaml theme={null}
      backendTLS:
        hostname: backend.internal.example.com
      ```
    </ParamField>

    <ParamField body="backendTLS.insecure" type="boolean">
      When `true`, Agentgateway skips all certificate verification for the backend connection. **Not recommended for production.**

      ```yaml theme={null}
      backendTLS:
        insecure: true
      ```
    </ParamField>

    <ParamField body="backendTLS.insecureHost" type="boolean">
      When `true`, Agentgateway skips hostname verification but still validates the certificate chain.

      ```yaml theme={null}
      backendTLS:
        insecureHost: true
      ```
    </ParamField>

    <ParamField body="backendTLS.alpn" type="string[]">
      Application-Layer Protocol Negotiation (ALPN) protocols to advertise during the TLS handshake.

      ```yaml theme={null}
      backendTLS:
        alpn:
        - h2
        - http/1.1
      ```
    </ParamField>

    <ParamField body="backendTLS.subjectAltNames" type="string[]">
      List of acceptable Subject Alternative Names (SANs) in the backend's certificate. When set, Agentgateway verifies that the backend certificate contains at least one of these SANs.

      ```yaml theme={null}
      backendTLS:
        subjectAltNames:
        - backend.example.com
        - backend-alt.example.com
      ```
    </ParamField>
  </Expandable>
</ParamField>

## Examples

<AccordionGroup>
  <Accordion title="HTTPS listener with TLS 1.3 only">
    ```yaml theme={null}
    binds:
    - port: 443
      listeners:
      - name: secure
        protocol: HTTPS
        tls:
          cert: /etc/ssl/certs/server.crt
          key: /etc/ssl/private/server.key
          minTLSVersion: "1.3"
          maxTLSVersion: "1.3"
        routes:
        - backends:
          - mcp:
              targets:
              - name: everything
                stdio:
                  cmd: npx
                  args: ["@modelcontextprotocol/server-everything"]
    ```
  </Accordion>

  <Accordion title="Mutual TLS listener">
    ```yaml theme={null}
    binds:
    - port: 443
      listeners:
      - name: mtls
        protocol: HTTPS
        tls:
          cert: /etc/ssl/certs/server.crt
          key: /etc/ssl/private/server.key
          root: /etc/ssl/certs/ca.pem
    ```
  </Accordion>

  <Accordion title="Backend with mTLS">
    ```yaml theme={null}
    binds:
    - port: 3000
      listeners:
      - routes:
        - policies:
            backendTLS:
              cert: /etc/ssl/client.crt
              key: /etc/ssl/client.key
              root: /etc/ssl/certs/backend-ca.pem
              hostname: backend.example.com
              alpn:
              - h2
          backends:
          - host: https://backend.example.com
    ```
  </Accordion>
</AccordionGroup>

<Warning>
  Setting `insecure: true` disables all certificate verification. Only use this for local development or in fully trusted private networks. Never use it in production environments.
</Warning>

<Note>
  Listener TLS requires setting the `protocol` field on the listener to `HTTPS`. Routes under that listener will receive decrypted traffic.
</Note>