Enable or disable the firewall

Deferred Asynchronous · 202

PUT /api/v1/servers/{vmid}/firewall

operationIdputServerFirewall

Required level: Operations to enable, Full to disable
Rate limit: mutation, 300 calls per hour

Enables or disables filtering on the VPS, then updates its rules.

Enabling applies the rules of the rule sets applied to the VPS: once the firewall is active, any incoming traffic not allowed by one of them is blocked, over IPv4 and IPv6 alike. With no rule set applied, it has no effect and enabled stays false: apply a rule set first (POST /servers/{vmid}/firewall/sets/{id}).

The required level depends on the direction of the change: enabling (enabled: true) protects the machine, so an Operations key is enough; disabling (enabled: false) exposes it, so a Full key is required.

The tasks array may be empty if the synchronization task is not yet visible when the response is sent: the state can then be read with GET /servers/{vmid}/firewall.

This request is processed in the background: it answers immediately while the work continues. Follow it with the task or request endpoints.

Path parameters

vmid string required: Identifier of the VPS. It must belong to the account and be within the key's scope.

pattern ^\d+$ Example: 116807

Request body

application/json

enabled boolean

true: enable filtering; false: disable it

required

Example request

{
  "enabled": true
}

Responses

202

Request accepted and queued. Track the returned task with GET /tasks/{id}.

The request was accepted, not completed. The response carries a task to follow.

{
  "data": {
    "tasks": [
      {
        "id": "tsk_000002e1",
        "status": "pending",
        "action": "firewall.sync",
        "vmid": "116807",
        "description": "Mise à jour des règles Firewall pour la VM : 116807",
        "created_at": "2026-08-20T14:31:02+02:00",
        "finished_at": null
      }
    ]
  }
}

Response fields 9

data object
tasks object[]

Tasks created; always an array
id string

Opaque identifier

Example: tsk_000002e1
status string

unknown would indicate a state the API cannot name

one of: pending, succeeded, failed, unknown
action string

Type of task

one of: server.start, server.stop, server.shutdown, server.reboot, server.reset, server.rebuild, server.enable_rescue, server.disable_rescue, server.reboot_rescue, snapshot.create, snapshot.delete, snapshot.rollback, backup.create, backup.restore, iso.mount, iso.unmount, firewall.sync, firewall.unblock_port_25 TaskAction
vmid string
description string
created_at string (date-time)
finished_at string (date-time)

null while the task is running

400

Invalid parameters: validation_failed — enabled missing or not a boolean.

{
  "type": "https://docs.lws.fr/kvm/errors/validation-failed",
  "title": "Paramètres invalides",
  "status": 400,
  "code": "validation_failed",
  "detail": "Paramètre « enabled » invalide.",
  "request_id": "3f9a1c07b2e45d18",
  "errors": {
    "enabled": "Booléen attendu : true pour activer le pare-feu, false pour le désactiver."
  }
}

Response fields 18

type string (uri)

Example: https://docs.lws.fr/kvm/errors/vm-not-found

required
title string

Short title, in French

Example: VPS introuvable

required
status integer (int64)

HTTP status

Example: 404

required
code string

Stable machine-readable code (see "Errors" in Getting started)

Example: vm_not_found

required
detail string

Detailed message, in French

Example: Aucun VPS 999999 sur ce compte.

required
request_id string

Identifier of the request, to give to support

Example: 3f9a1c07b2e45d18

required
errors object

validation_failed: message per faulty parameter
required_level string

insufficient_scope: level required by the operation

one of: read, exploitation, full
task_id string

task_already_running: task running on this VPS

Example: tsk_000002d5
family string

rate_limited: exhausted rate limit family

one of: read, mutation, heavy
limit integer (int64)

rate_limited: hourly limit of the family
retry_after integer (int64)

rate_limited: seconds to wait
lock string

server_locked: lock set by the hypervisor (backup, snapshot, suspended…)

Example: snapshot
reason string

server_locked: operation_in_progress, an operation is running, retry after Retry-After; suspended, the VPS is hibernating, start it first; support_notified, abnormal lock, the LWS team has been notified and is taking care of it

one of: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: nature of the intervention, start and expected end (null for an incident)
kind string

one of: works, incident
started_at string (date-time)
expected_end string (date-time)

401

Authentication refused: invalid_token — Authorization header missing or malformed, or unknown key; access_disabled — API access turned off for this account, or API service temporarily turned off by LWS.

Authorization header missing or malformed, or unknown key

{
  "type": "https://docs.lws.fr/kvm/errors/invalid-token",
  "title": "Authentification invalide",
  "status": 401,
  "code": "invalid_token",
  "detail": "Clé inconnue ou révoquée.",
  "request_id": "3f9a1c07b2e45d18"
}

API access turned off for this account, or API service temporarily turned off by LWS

{
  "type": "https://docs.lws.fr/kvm/errors/access-disabled",
  "title": "Accès API désactivé",
  "status": 401,
  "code": "access_disabled",
  "detail": "L'accès API est désactivé pour ce compte. Réactivez-le depuis la page « API / MCP » du panel.",
  "request_id": "3f9a1c07b2e45d18"
}

Response fields 18

type string (uri)

Example: https://docs.lws.fr/kvm/errors/vm-not-found

required
title string

Short title, in French

Example: VPS introuvable

required
status integer (int64)

HTTP status

Example: 404

required
code string

Stable machine-readable code (see "Errors" in Getting started)

Example: vm_not_found

required
detail string

Detailed message, in French

Example: Aucun VPS 999999 sur ce compte.

required
request_id string

Identifier of the request, to give to support

Example: 3f9a1c07b2e45d18

required
errors object

validation_failed: message per faulty parameter
required_level string

insufficient_scope: level required by the operation

one of: read, exploitation, full
task_id string

task_already_running: task running on this VPS

Example: tsk_000002d5
family string

rate_limited: exhausted rate limit family

one of: read, mutation, heavy
limit integer (int64)

rate_limited: hourly limit of the family
retry_after integer (int64)

rate_limited: seconds to wait
lock string

server_locked: lock set by the hypervisor (backup, snapshot, suspended…)

Example: snapshot
reason string

server_locked: operation_in_progress, an operation is running, retry after Retry-After; suspended, the VPS is hibernating, start it first; support_notified, abnormal lock, the LWS team has been notified and is taking care of it

one of: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: nature of the intervention, start and expected end (null for an incident)
kind string

one of: works, incident
started_at string (date-time)
expected_end string (date-time)

403

Access denied: insufficient_scope — key level too low; ip_not_allowed — calling address not authorized.

key level too low

{
  "type": "https://docs.lws.fr/kvm/errors/insufficient-scope",
  "title": "Droits insuffisants",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "Niveau de permission « exploitation » requis.",
  "request_id": "3f9a1c07b2e45d18",
  "required_level": "exploitation"
}

calling address not authorized

{
  "type": "https://docs.lws.fr/kvm/errors/ip-not-allowed",
  "title": "Adresse non autorisée",
  "status": 403,
  "code": "ip_not_allowed",
  "detail": "L'adresse 203.0.113.10 ne figure pas parmi les adresses autorisées de ce compte.",
  "request_id": "3f9a1c07b2e45d18"
}

Response fields 18

type string (uri)

Example: https://docs.lws.fr/kvm/errors/vm-not-found

required
title string

Short title, in French

Example: VPS introuvable

required
status integer (int64)

HTTP status

Example: 404

required
code string

Stable machine-readable code (see "Errors" in Getting started)

Example: vm_not_found

required
detail string

Detailed message, in French

Example: Aucun VPS 999999 sur ce compte.

required
request_id string

Identifier of the request, to give to support

Example: 3f9a1c07b2e45d18

required
errors object

validation_failed: message per faulty parameter
required_level string

insufficient_scope: level required by the operation

one of: read, exploitation, full
task_id string

task_already_running: task running on this VPS

Example: tsk_000002d5
family string

rate_limited: exhausted rate limit family

one of: read, mutation, heavy
limit integer (int64)

rate_limited: hourly limit of the family
retry_after integer (int64)

rate_limited: seconds to wait
lock string

server_locked: lock set by the hypervisor (backup, snapshot, suspended…)

Example: snapshot
reason string

server_locked: operation_in_progress, an operation is running, retry after Retry-After; suspended, the VPS is hibernating, start it first; support_notified, abnormal lock, the LWS team has been notified and is taking care of it

one of: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: nature of the intervention, start and expected end (null for an incident)
kind string

one of: works, incident
started_at string (date-time)
expected_end string (date-time)

404

Resource not found: vm_not_found — VPS does not exist or is outside the key's scope.

{
  "type": "https://docs.lws.fr/kvm/errors/vm-not-found",
  "title": "VPS introuvable",
  "status": 404,
  "code": "vm_not_found",
  "detail": "Aucun VPS 999999 sur ce compte.",
  "request_id": "3f9a1c07b2e45d18"
}

Response fields 18

type string (uri)

Example: https://docs.lws.fr/kvm/errors/vm-not-found

required
title string

Short title, in French

Example: VPS introuvable

required
status integer (int64)

HTTP status

Example: 404

required
code string

Stable machine-readable code (see "Errors" in Getting started)

Example: vm_not_found

required
detail string

Detailed message, in French

Example: Aucun VPS 999999 sur ce compte.

required
request_id string

Identifier of the request, to give to support

Example: 3f9a1c07b2e45d18

required
errors object

validation_failed: message per faulty parameter
required_level string

insufficient_scope: level required by the operation

one of: read, exploitation, full
task_id string

task_already_running: task running on this VPS

Example: tsk_000002d5
family string

rate_limited: exhausted rate limit family

one of: read, mutation, heavy
limit integer (int64)

rate_limited: hourly limit of the family
retry_after integer (int64)

rate_limited: seconds to wait
lock string

server_locked: lock set by the hypervisor (backup, snapshot, suspended…)

Example: snapshot
reason string

server_locked: operation_in_progress, an operation is running, retry after Retry-After; suspended, the VPS is hibernating, start it first; support_notified, abnormal lock, the LWS team has been notified and is taking care of it

one of: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: nature of the intervention, start and expected end (null for an incident)
kind string

one of: works, incident
started_at string (date-time)
expected_end string (date-time)

409

Conflict with the current state: task_already_running — a firewall synchronization or a reinstallation is already running; service_suspended — VPS disabled or expired: only read operations remain possible.

a firewall synchronization or a reinstallation is already running

{
  "type": "https://docs.lws.fr/kvm/errors/task-already-running",
  "title": "Opération déjà en cours",
  "status": 409,
  "code": "task_already_running",
  "detail": "Une synchronisation du pare-feu est déjà en cours sur ce VPS. Attendez qu'elle aboutisse.",
  "request_id": "3f9a1c07b2e45d18",
  "task_id": "tsk_000002d5"
}

VPS disabled or expired: only read operations remain possible

{
  "type": "https://docs.lws.fr/kvm/errors/service-suspended",
  "title": "Service suspendu",
  "status": 409,
  "code": "service_suspended",
  "detail": "Le VPS 116807 est expiré.",
  "request_id": "3f9a1c07b2e45d18"
}

Response fields 18

type string (uri)

Example: https://docs.lws.fr/kvm/errors/vm-not-found

required
title string

Short title, in French

Example: VPS introuvable

required
status integer (int64)

HTTP status

Example: 404

required
code string

Stable machine-readable code (see "Errors" in Getting started)

Example: vm_not_found

required
detail string

Detailed message, in French

Example: Aucun VPS 999999 sur ce compte.

required
request_id string

Identifier of the request, to give to support

Example: 3f9a1c07b2e45d18

required
errors object

validation_failed: message per faulty parameter
required_level string

insufficient_scope: level required by the operation

one of: read, exploitation, full
task_id string

task_already_running: task running on this VPS

Example: tsk_000002d5
family string

rate_limited: exhausted rate limit family

one of: read, mutation, heavy
limit integer (int64)

rate_limited: hourly limit of the family
retry_after integer (int64)

rate_limited: seconds to wait
lock string

server_locked: lock set by the hypervisor (backup, snapshot, suspended…)

Example: snapshot
reason string

server_locked: operation_in_progress, an operation is running, retry after Retry-After; suspended, the VPS is hibernating, start it first; support_notified, abnormal lock, the LWS team has been notified and is taking care of it

one of: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: nature of the intervention, start and expected end (null for an incident)
kind string

one of: works, incident
started_at string (date-time)
expected_end string (date-time)

429

Rate limit exceeded: rate_limited — hourly limit of the family exhausted.

{
  "type": "https://docs.lws.fr/kvm/errors/rate-limited",
  "title": "Quota dépassé",
  "status": 429,
  "code": "rate_limited",
  "detail": "Quota dépassé pour les opérations de type « mutation » : 300 appels par heure. Réessayez dans 95 seconde(s).",
  "request_id": "3f9a1c07b2e45d18",
  "family": "mutation",
  "limit": 300,
  "retry_after": 95
}

Response fields 18

type string (uri)

Example: https://docs.lws.fr/kvm/errors/vm-not-found

required
title string

Short title, in French

Example: VPS introuvable

required
status integer (int64)

HTTP status

Example: 404

required
code string

Stable machine-readable code (see "Errors" in Getting started)

Example: vm_not_found

required
detail string

Detailed message, in French

Example: Aucun VPS 999999 sur ce compte.

required
request_id string

Identifier of the request, to give to support

Example: 3f9a1c07b2e45d18

required
errors object

validation_failed: message per faulty parameter
required_level string

insufficient_scope: level required by the operation

one of: read, exploitation, full
task_id string

task_already_running: task running on this VPS

Example: tsk_000002d5
family string

rate_limited: exhausted rate limit family

one of: read, mutation, heavy
limit integer (int64)

rate_limited: hourly limit of the family
retry_after integer (int64)

rate_limited: seconds to wait
lock string

server_locked: lock set by the hypervisor (backup, snapshot, suspended…)

Example: snapshot
reason string

server_locked: operation_in_progress, an operation is running, retry after Retry-After; suspended, the VPS is hibernating, start it first; support_notified, abnormal lock, the LWS team has been notified and is taking care of it

one of: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: nature of the intervention, start and expected end (null for an incident)
kind string

one of: works, incident
started_at string (date-time)
expected_end string (date-time)

502

Dependency unreachable: hypervisor_unreachable — hypervisor database not responding, nothing was changed; upstream_unavailable — VPS inventory temporarily unavailable.

hypervisor database not responding, nothing was changed

{
  "type": "https://docs.lws.fr/kvm/errors/hypervisor-unreachable",
  "title": "Hyperviseur injoignable",
  "status": 502,
  "code": "hypervisor_unreachable",
  "detail": "La base de l'hyperviseur n'a pas répondu, le pare-feu n'a pas été modifié.",
  "request_id": "3f9a1c07b2e45d18"
}

VPS inventory temporarily unavailable

{
  "type": "https://docs.lws.fr/kvm/errors/upstream-unavailable",
  "title": "Service momentanément indisponible",
  "status": 502,
  "code": "upstream_unavailable",
  "detail": "Inventaire des VM indisponible.",
  "request_id": "3f9a1c07b2e45d18"
}

Response fields 18

type string (uri)

Example: https://docs.lws.fr/kvm/errors/vm-not-found

required
title string

Short title, in French

Example: VPS introuvable

required
status integer (int64)

HTTP status

Example: 404

required
code string

Stable machine-readable code (see "Errors" in Getting started)

Example: vm_not_found

required
detail string

Detailed message, in French

Example: Aucun VPS 999999 sur ce compte.

required
request_id string

Identifier of the request, to give to support

Example: 3f9a1c07b2e45d18

required
errors object

validation_failed: message per faulty parameter
required_level string

insufficient_scope: level required by the operation

one of: read, exploitation, full
task_id string

task_already_running: task running on this VPS

Example: tsk_000002d5
family string

rate_limited: exhausted rate limit family

one of: read, mutation, heavy
limit integer (int64)

rate_limited: hourly limit of the family
retry_after integer (int64)

rate_limited: seconds to wait
lock string

server_locked: lock set by the hypervisor (backup, snapshot, suspended…)

Example: snapshot
reason string

server_locked: operation_in_progress, an operation is running, retry after Retry-After; suspended, the VPS is hibernating, start it first; support_notified, abnormal lock, the LWS team has been notified and is taking care of it

one of: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: nature of the intervention, start and expected end (null for an incident)
kind string

one of: works, incident
started_at string (date-time)
expected_end string (date-time)

503

Host server under intervention: server_maintenance — host server under an intervention announced by LWS and unreachable; honor Retry-After.

{
  "type": "https://docs.lws.fr/kvm/errors/server-maintenance",
  "title": "Intervention en cours sur le serveur hôte",
  "status": 503,
  "code": "server_maintenance",
  "detail": "Le serveur hébergeant ce VPS fait l'objet d'une intervention programmée par LWS : il est momentanément inaccessible. Fin prévue : 2026-10-21T18:00:00+02:00.",
  "request_id": "3f9a1c07b2e45d18",
  "maintenance": {
    "kind": "works",
    "started_at": "2026-10-21T14:00:00+02:00",
    "expected_end": "2026-10-21T18:00:00+02:00"
  }
}

Response fields 18

type string (uri)

Example: https://docs.lws.fr/kvm/errors/vm-not-found

required
title string

Short title, in French

Example: VPS introuvable

required
status integer (int64)

HTTP status

Example: 404

required
code string

Stable machine-readable code (see "Errors" in Getting started)

Example: vm_not_found

required
detail string

Detailed message, in French

Example: Aucun VPS 999999 sur ce compte.

required
request_id string

Identifier of the request, to give to support

Example: 3f9a1c07b2e45d18

required
errors object

validation_failed: message per faulty parameter
required_level string

insufficient_scope: level required by the operation

one of: read, exploitation, full
task_id string

task_already_running: task running on this VPS

Example: tsk_000002d5
family string

rate_limited: exhausted rate limit family

one of: read, mutation, heavy
limit integer (int64)

rate_limited: hourly limit of the family
retry_after integer (int64)

rate_limited: seconds to wait
lock string

server_locked: lock set by the hypervisor (backup, snapshot, suspended…)

Example: snapshot
reason string

server_locked: operation_in_progress, an operation is running, retry after Retry-After; suspended, the VPS is hibernating, start it first; support_notified, abnormal lock, the LWS team has been notified and is taking care of it

one of: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: nature of the intervention, start and expected end (null for an incident)
kind string

one of: works, incident
started_at string (date-time)
expected_end string (date-time)

Enable or disable the firewall

Path parameters

Request body

Responses

Report an error

AI assistant