Skip to main content

Version: 3.9.0

Configure HTTPS Between Client and APISIX

TLS (Transport Layer Security) is a cryptographic protocol designed to secure communication between two entities. Enforcing HTTPS between clients and APISIX improves the security and authenticity during the data transmission.

This guide will show you how to configure HTTPS between client applications and APISIX.

TLS between APISIX and Upstream


Create a Route

Create a route that forwards all requests to /ip to the upstream

curl -i "" -X PUT -d '
"id": "quickstart-client-ip",
"uri": "/ip",
"upstream": {
"nodes": {
"type": "roundrobin"

An HTTP/1.1 200 OK response verifies that the route is created successfully.

Generate Certificates and Keys

Generate the certificate authority (CA) key and certificate:

openssl genrsa -out ca.key 2048 && \
openssl req -new -sha256 -key ca.key -out ca.csr -subj "/CN=ROOTCA" && \
openssl x509 -req -days 36500 -sha256 -extensions v3_ca -signkey ca.key -in ca.csr -out ca.crt

Generate the key and certificate with the common name for APISIX, and sign with the CA certificate:

openssl genrsa -out server.key 2048 && \
openssl req -new -sha256 -key server.key -out server.csr -subj "/" && \
openssl x509 -req -days 36500 -sha256 -extensions v3_req \
-CA ca.crt -CAkey ca.key -CAserial -CAcreateserial \
-in server.csr -out server.crt

Configure HTTPS for APISIX

Load the content stored in server.crt and server.key into environment variables:

server_cert=$(cat server.crt)
server_key=$(cat server.key)

Create an SSL certificate object to save the server certificate and its key:

curl -i "" -X PUT -d '
"id": "quickstart-tls-client-ssl",
"sni": "",
"cert": "'"${server_cert}"'",
"key": "'"${server_key}"'"

sni:, the same as server certificate CN value

cert: server certificate

key: private key for the server certificate

Verify HTTPS between Client and APISIX

As the certificate is only valid for the CN, you should use as the domain name where APISIX is hosted.

Send a request to and resolve to

curl -ikv --resolve "" ""

A TLS handshake process similar to the following verifies the TLS between client and APISIX is enabled:

* Added to DNS cache
* Hostname was found in DNS cache
* Trying
* Connected to ( port 9443 (#0)
* ALPN, offering h2
* ALPN, offering http/1.1
* successfully set certificate verify locations:
* CAfile: /etc/ssl/certs/ca-certificates.crt
* CApath: /etc/ssl/certs
* TLSv1.3 (OUT), TLS handshake, Client hello (1):
* TLSv1.3 (IN), TLS handshake, Server hello (2):
* TLSv1.3 (IN), TLS handshake, Encrypted Extensions (8):
* TLSv1.3 (IN), TLS handshake, Certificate (11):
* TLSv1.3 (IN), TLS handshake, CERT verify (15):
* TLSv1.3 (IN), TLS handshake, Finished (20):
* TLSv1.3 (OUT), TLS change cipher, Change cipher spec (1):
* TLSv1.3 (OUT), TLS handshake, Finished (20):
* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384
* ALPN, server accepted to use h2
* Server certificate:
* subject:
* start date: Apr 21 07:47:54 2023 GMT
* expire date: Mar 28 07:47:54 2123 GMT
* issuer: CN=ROOTCA
* SSL certificate verify result: unable to get local issuer certificate (20), continuing anyway.
* Using HTTP2, server supports multi-use
* Connection state changed (HTTP/2 confirmed)
* Copying HTTP/2 data in stream buffer to connection buffer after upgrade: len=0
* Using Stream ID: 1 (easy handle 0x556274d632e0)
> GET /ip HTTP/2
> Host:
> user-agent: curl/7.74.0
> accept: */*
* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
* old SSL session ID is stale, removing
* Connection state changed (MAX_CONCURRENT_STREAMS == 128)!
< HTTP/2 200
HTTP/2 200

Next Steps

You can learn more about TLS and APISIX SSL object in SSL Certificates.

APISIX also supports mTLS connection between clients and APISIX. See Configure mTLS between client and APISIX for more details. Logo

API Management for Modern Architectures with Edge, API Gateway, Kubernetes, and Service Mesh.


API7 Cloud

SOC2 Type IRed Herring

Copyright © APISEVEN Ltd. 2019 – 2024. Apache, Apache APISIX, APISIX, and associated open source project names are trademarks of the

Apache Software Foundation