Skip to content

Access WSO2 API Manager through a custom proxy path

Adding a custom proxy path is useful when you have a proxy server fronting your product server. In this scenario, the "custom proxy path" is used for mapping a proxy URL with the actual URL of your server, which allows clients to access the server with the proxy URL.

In the following hypothetical scenario, devportal, publisher, admin, and carbon console apps are hosted in the domain as follows.



Once you have configured your products with a proxy server, it will no longer be possible to access the product behind the proxy.

In the above example, "apim" is the "proxy context paths" of API Manager.

When a client sends a request to the proxy entry URL path, e.g. , the request is directed to the back-end service URL (https://:9443/carbon) where the original service lies. Eventually, the client has to be served via the requested proxy entry URL path. The mapping between the proxy URL path and the back-end service URL path is resolved by the reverse proxy server fronting the back-end service.

Step 1: Install and configure a reverse proxy

  1. Download nginx server .
  2. Install the nginx server in your deployment server by executing the following command:

    sudo apt-get install nginx
  3. Create a folder called "ssl" inside /etc/nginx, and create the ssl certificates inside this folder by executing the following commands:

    sudo mkdir /etc/nginx/ssl
    cd /etc/nginx/ssl
  4. The next step is to create the server key and certificates. First create the private key as shown below. Note that a passphrase is prompted when creating the private key.

    sudo openssl genrsa -des3 -out server.key 1024
  5. Next, create the certificate signing request as shown below.

    Fill in the required details. The most important entry is the Common Name. Enter the domain name or the IP address if there is no domain name. In the current example, we can give

    sudo openssl req -new -key server.key -out server.csr
  6. Next step is to sign the SSL certificate using the following command:

    sudo openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

    The certificate is now created.

  7. The last step is to set up the virtual host displaying the new certificate. Create a copy of the default, "sites-enabled" configuration using the following command:

    cp /etc/nginx/sites-available/default /etc/nginx/sites-available/wso2

    If your Nginx installation does not contain "sites-enabled" and "sites-available" folders, follow the steps given below.

    1. Create /etc/nginx/sites-available and /etc/nginx/sites-enabled.
    2. Open /etc/nginx/nginx.conf
    3. Add include /etc/nginx/sites-enabled/*; into the http block.
  8. Now, create a symbolic between the "sites-enabled" directory and the "sites-available" directory using the following command:

    ln -s /etc/nginx/sites-available/wso2 /etc/nginx/sites-enabled/wso2

    The host is now activated.

  9. Open the /etc/nginx/sites-enabled/wso2 file and enter the following configurations.

    server {
            listen 443 ssl default_server;
            listen [::]:443 default_server ipv6only=on;
            access_log  /var/log/nginx/proxy.log;
            ssl_certificate /etc/nginx/ssl/server.crt;
            ssl_certificate_key /etc/nginx/ssl/server.key;
            ssl_session_timeout  5m;
            ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
            ssl_ciphers  HIGH:!aNULL:!MD5;
            ssl_prefer_server_ciphers   on;
            rewrite \w*(admin|devportal|publisher)$ $1/ permanent;
            location /apim/ {   
                proxy_set_header X-Forwarded-Host $host;
                proxy_set_header X-Forwarded-Server $host;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header Host $http_host;
                proxy_read_timeout 5m;
                proxy_send_timeout 5m;
                proxy_pass https://localhost:9443/;
                proxy_http_version 1.1;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection "upgrade";
  10. Save the file and restart the Nginx server using the following command to complete the Nginx configuration:

    sudo nginx -s reload
    Or start the Nginx server if it's not running.

    sudo nginx

Step 2: Add host entries

Add the following host entries

Step 3: Update the API Manager configuration - deployment.toml

Open repository/conf/deployment.toml and add or update the following configurations.

hostname = ""
node_ip = ""
mode = "single" #single or ha
base_path = "${carbon.protocol}://${}:${}/apim"
server_role = "default"
proxy_context_path = "/apim"

url = ""

proxyPort = 443


  1. The hostname is set to ""
  2. base_path has a suffix of "/apim" which is the proxy_context_path
  3. proxy_context_path is set to "/apim"

Step 4: Update the API Manager web app configurations

Add the following configuration to each web application.


"context": "/apim/devportal", 
"proxy_context_path": "/apim",


"context": "/apim/publisher", 
"proxy_context_path": "/apim",


"context": "/apim/admin", 
"proxy_context_path": "/apim",

Now start/restart the API Manager server

The API Manager web applications will be accessible as expected.