SSL Certificates

SSL certificates in API7 Enterprise (API7 Gateway) are used to encrypt traffic between clients and the gateway (TLS termination) and between the gateway and upstream services (re-encryption). The control plane provides a centralized management system for certificates, supporting automated SNI matching and secure storage through external secret managers.

How SSL termination works

When a client initiates a TLS connection to API7 Gateway, the gateway uses the Server Name Indication (SNI) provided in the TLS handshake to select the appropriate certificate.

SSL certificate fields

An SSL entity in API7 Gateway contains the public certificate, the private key, and the associated domains (SNIs).

• Name: A descriptive name for the certificate.
• SNIs: An array of Server Name Indication values (e.g., example.com, *.example.com). The gateway uses these to match incoming connections.
• Certificate (Cert/Certs): The PEM-encoded public certificate. Multiple certificates can be provided for dual-stack (RSA/ECC) support.
• Private Key (Key/Keys): The PEM-encoded private key corresponding to the certificate.
• Client CA: Used for Mutual TLS (mTLS). If provided, the gateway will verify the client's certificate against this CA.
• Type: Currently supports server, representing certificates used by the gateway to verify client requests.

Secret references

For enhanced security, API7 Gateway supports referencing certificates and keys stored in external secret managers instead of providing them in plaintext.

You can use the $secret:// or $env:// prefix in the cert and key fields:

• HashiCorp Vault: $secret://vault/path/to/secret
• AWS Secrets Manager: $secret://aws/secret-id
• Environment Variables: $env://CERT_NAME

This ensures that sensitive private keys never reside in the control plane database in plaintext and are only fetched by the data plane nodes at runtime.

Certificate rotation

API7 Gateway supports hitless certificate rotation. When you update an SSL entity in the control plane, the changes are synchronized to all data plane nodes. The gateway swaps the certificate in memory without dropping active connections or requiring a reload.

Mutual TLS (mTLS)

To restrict access to specific clients, you can configure mTLS by adding a Client CA certificate to the SSL entity. When enabled, the gateway will request a certificate from the client during the TLS handshake and verify it against the client.ca field. Requests with missing or invalid client certificates are rejected before reaching any routing logic.

Next steps

• Secure Credentials — manage secrets and sensitive data.
• Mutual TLS between Control Plane and Data Plane — secure CP-DP communication.
• Services and Routes — learn how services and routes work together.