Setting up SSL offloading via API

Reviewed on June 02, 2025

SSL offloading describes a pattern where the Load Balancer terminates encrypted connections at the frontend (decrypting incoming traffic), to forward it unencrypted to the backend servers. This effectively “offloads” the work of decrypting traffic from the backend server to the Load Balancer.

You can read more about SSL offloading, compared to SSL bridging or passthrough, in our dedicated documentation

This page shows you how to create a Load Balancer configured for SSL offloading using the Load Balancer API.

Before you start

To complete the actions presented below, you must have:

A Scaleway account logged into the console
Owner status or IAM permissions allowing you to perform actions in the intended Organization

Setting up your environment

Before configuring the Load Balancer from the API, prepare your environment to facilitate usage of the API.

Ensure you have generated an API key, and that you have the secret key to hand.
Get your Project ID from the Scaleway console.
Decide the Availability Zone for your Load Balancer.

Set these elements as environment variables as follows:

export SCW_SECRET_KEY="<YOUR SECRET KEY>"
export SCW_DEFAULT_ZONE="<YOUR AVAILABILITY ZONE>"
export SCW_PROJECT_ID="<YOUR PROJECT ID>"

Creating the Load Balancer

Create a new Load Balancer by running the following API call. Customize the name, description and tags:

curl -X POST \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  "https://api.scaleway.com/lb/v1/zones/$SCW_DEFAULT_ZONE/lbs" \
  -d '{
    "name":"API Test LB",
    "description": "my new Load Balancer",
    "project_id":"'"$SCW_PROJECT_ID"'",
    "tags":["test","another tag"]
  }'

The output of the API call returns a json output, similar to the example below where:

The first line starting with id displays the ID of the newly-created Load Balancer.
The line starting with ip_address displays the Load Balancer's IP address.

{
  "id":"625f3892-13ex-xxxx-xxxx-xxxxxxxxxxxxx",
  "name":"API Test LB",
  "description":"my new Load Balancer",
  "status":"to_create",
  "instances":[
      
  ],
  "organization_id":"2ea18278-xxxx-xxxx-xxxx-xxxxxxxxxxxxxx",
  "project_id":"2ea18278-xxxx-xxxx-xxxx-xxxxxxxxxxxxxx",
  "ip":[
      {
        "id":"8802d6eb-abb6-4f35-a4f7-685182be39ab",
        "ip_address":"195.154.72.139",
        "organization_id":"2ea18278-xxxx-xxxx-xxxx-xxxxxxxxxxxxxx",
        "project_id":"2ea18278-xxxx-xxxx-xxxx-xxxxxxxxxxxxxx",
        "lb_id":"625f3892-13ex-xxxx-xxxx-xxxxxxxxxxxxx",
        "reverse":"195-154-72-139.lb.fr-par.scw.cloud",
        "tags":[
            
        ],
        "region":"fr-par",
        "zone":"fr-par-1"
      }
  ],
  "tags":[
      "test",
      "another tag"
  ],
  "frontend_count":0,
  "backend_count":0,
  "type":"lb-s",
  "subscriber":null,
  "ssl_compatibility_level":"ssl_compatibility_level_intermediate",
  "created_at":"2024-05-28T08:52:54.473341297Z",
  "updated_at":"2024-05-28T08:52:54.473341297Z",
  "private_network_count":0,
  "route_count":0,
  "region":"fr-par",
  "zone":"fr-par-1"
}

Copy the id field of the response. Save this ID to a variable to use in the next steps.
```
export LOAD_BALANCER_ID="<YOUR LOAD BALANCER ID>"
```

Creating a backend

This tutorial supposes that a web application is running on port 80 of the backend machines.

Create a new backend for your Load Balancer. Make sure to replace <YOUR FIRST SERVER IP> and <YOUR SECOND SERVER IP> with the IPs of your backend servers:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  "https://api.scaleway.com/lb/v1/zones/$SCW_DEFAULT_ZONE/lbs/$LOAD_BALANCER_ID/backends" \
  -d '{
    "name":"main backend",
    "forward_port": 80,
    "forward_port_algorithm": "roundrobin",
    "forward_protocol": "tcp",
    "health_check":{
        "check_delay": 2000,
        "check_max_retries": 3,
        "check_timeout": 1000,
        "port": 80,
        "tcp_config":{}
    }, 
    "server_ip": ["<YOUR FIRST SERVER IP>", "<YOUR SECOND SERVER IP>"]
  }'

A json output similar to the first request displays.

Copy the value of the first line of the output, starting with id. This is the ID of your Load Balancer's backend. Set it as a variable:
```
export BACKEND_ID="<YOUR BACKEND ID>"
```

Creating an SSL/TLS certificate

In order to achieve SSL offloading, your Load Balancer needs an SSL/TLS certificate. In these steps, we create a Let's Encrypt certificate, which we will then add to the Load Balancer's frontend.

Create a new certificate for your Load Balancer. Replace <YOUR CERTIFICATE NAME> with a friendly name for the certificate, and <YOUR DOMAIN NAME> with your domain name (this domain must exist and resolve to your Load Balancer IP address).

curl -X POST \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  "https://api.scaleway.com/lb/v1/zones/$SCW_DEFAULT_ZONE/lbs/$LOAD_BALANCER_ID/certificates" \
  -d '{
    "name":"<YOUR CERTIFICATE NAME>",
    "letsencrypt":{
      "common_name":"<YOUR DOMAIN NAME>"
    }
  }'

The certificate details are returned in the form of a json list.

Copy the value of the first line of the output, starting with id. This is the ID of your Load Balancer's certificate. Set it as a variable:
```
export CERTIFICATE_ID="<YOUR CERTIFICATE ID>"
```

Creating a frontend

Create a frontend for your Load Balancer by specifying the Load Balancer ID, backend ID and certificate ID. In the example below, we define the inbound_port as 443 (the default HTTPS port). The frontend will listen on this port for incoming connections.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  "https://api.scaleway.com/lb/v1/zones/$SCW_DEFAULT_ZONE/lbs/$LOAD_BALANCER_ID/frontends" \
  -d '{
    "name": "my frontend",
    "backend_id": "'"$BACKEND_ID"'",
    "inbound_port": 443,
    "timeout_client": 5000,
    "certificate_id": "'"$CERTIFICATE_ID"'"
  }'

The frontend details are returned in json format.

Conclusion

The Load Balancer is now up, configured with a Let's Encrypt SSL/TLS certificate, accepting HTTPS connections on port 443 and terminating the HTTPS sessions on the Load Balancer before connecting to the backends via a plain HTTP connection.

For more information about the configuration of a Load Balancer via the API, refer to the API documentation.

Still need help?

Create a support ticket