Suggest an edit

Setting up SSL Offloading via API

Reviewed on 13 November 2023Published on 26 May 2021

SSL offloading can be configured using the Load Balancers API.

Security & Identity (IAM)

To perform certain actions described below, you must either be the Owner of the Organization in which the actions will be performed or an IAM user with the necessary permissions.

  • You have an account and are logged into the Scaleway console.

Before configuring the Load Balancer from the API, prepare your environment to facilitate the API usage. Recover the secret_key and the organization_id from the Scaleway console or the API and set them as environment variables. Make sure you also have configured the geographical location of your Load Balancer:

export TOKEN="<secret_key>"
REGION="<choose your location (nl-ams/fr-par)>"
ORGANIZATION_ID="<your organization ID>"
  1. Create a new Load Balancer by running the following API call. Customize the name, description and tags:
    curl -X POST "$REGION/lbs" -H "accept: application/json" -H "X-Auth-Token: $SECRET_KEY" -H "Content-Type: application/json" \
    -d "{\"description\":\"YOUR DESCRIPTION\",\"name\":\"TEST\",\"organization_id\":\"$ORGANIZATION_ID\",\"tags\":[\"test\", \"step by step\"]}"

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 balanced IP.
"id": "6208ec73-2b0e-4b60-b449-7f6bd72fd522",
"name": "TEST",
"description": "YOUR DESCRIPTION",
"status": "pending",
"Instances": [],
"organization_id": "ORGANIZATION_ID",
"ip": [
"id": "7906bc2b-00cd-4548-8e06-ebfdf1e850be",
"ip_address": "",
"organization_id": "6208ec73-2f0a-8e06-9ea1-e53b4f625527",
"lb_id": "6208ec73-2b0e-4b60-b449-7f6bd72fd522",
"reverse": "",
"region": "fr-par"
"tags": [
"step by step"
"frontend_count": 0,
"backend_count": 0,
"region": "fr-par"
  1. Copy the id field of the response to use during the next steps. To simplify the use, save the ID to a variable, which will be used in the following steps.
  2. Create a new backend. This tutorial supposes that a web application is running on port 80 of the backend machines. Make sure to replace REPLACE-BY-IP-OF-YOUR-SERVER1 and REPLACE-BY-IP-OF-YOUR-SERVER2 with the IPs of the backend servers:
    curl -s -X POST "$REGION/lbs/$LB_ID/backends" -H "accept: application/json" -H "X-Auth-Token: $SECRET_KEY" -H "Content-Type: application/json" \
    -d "{\"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\":{}},\"name\":\"main backend\",\"send_proxy_v2\":false,\"server_ip\":[\"<REPLACE-BY-IP-OF-YOUR-SERVER1>\", \"<REPLACE-BY-IP-OF-YOUR-SERVER2>\"]} | jq ."

A json output similar to the first request displays. 4. Copy the value of the first line of the output, starting with id, and set it as a variable:

  1. Create the certificate by calling the API endpoint, after replacing YOUR-CERTFICATE-NAME with a friendly name for the certificate and REPLACE-BY-YOUR-DOMAIN-NAME with your domain name (i.e.
    curl -X POST "$REGION/lbs/$LB_ID/certificates" -H "accept: application/json" -H "X-Auth-Token: $SECRET_KEY" -H "Content-Type: application/json" -d "{\"name\":\"<YOUR-CERTIFICATE-NAME>\",\"letsencrypt\":{\"common_name\":\"<REPLACE-BY-YOUR-DOMAIN-NAME>\"}}"

The certificate details are presented in the form of a json list. 6. Copy the value of the first line of the list starting with id and set it as a variable:

  1. Create a new frontend by specifying the IDs of the Load Balancer, an existing backend and the certificate. Specify also the inbound_port (Port 443 for the default HTTPS port), on which the frontend will listen for incoming connections.
    curl -X POST "$REGION/lbs/$LB_ID/frontends" -H "accept: application/json" -H "X-Auth-Token: $SECRET_KEY" -H "Content-Type: application/json" \
    -d "{\"backend_id\":\"$BACKEND_ID\",\"inbound_port\":443,\"name\":\"main frontend\",\"timeout_client\":5000,\"certificate_id\": \"$CERT_ID\"}"

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.

Cloud Products & Resources
  • Scaleway Console
  • Compute
  • Storage
  • Network
  • IoT
  • AI
Dedicated Products & Resources
  • Dedibox Console
  • Dedibox Servers
  • Network
  • Web Hosting
  • Blog
  • Careers
  • Scaleway Learning
Follow us
ContractsLegal NoticePrivacy PolicyCookie PolicyDocumentation license
© 1999-2024 – Scaleway SAS