Update Mtls Endpoints

Update mTLS Config

PUT /v1/endpoints/{id}/mtls

Enable, switch mode, or disable mutual-TLS verification on an endpoint. Replaces the trusted-CA list wholesale on each call — pass the full list each time, the platform doesn't merge.

Enabling mTLS (mode != "disabled") is gated behind the mtls entitlement on your plan; disabling is unrestricted so a downgraded user can clear it themselves. optional and required modes need at least one CA in ca_ids — without one, the tunnel-server has nothing to validate against. Maximum 32 CAs per endpoint.

The handler validates that every CA ID in the list belongs to the calling user before persisting. The mode change + CA list replacement happen in a single transaction; partial state is impossible.

Path parameters

id string (uuid) Req

Endpoint UUID.

Request body

mode string Req

disabled | optional | required.

ca_ids int64[]

Trusted client-CA IDs (from /client-cas). Empty when mode: "disabled"; required (length ≥ 1) for optional and required. Max length 32.

Response (200 OK)

Returns the updated config — same shape as GET /v1/endpoints/{id}/mtls.

Errors

400 Bad Request

Invalid JSON, invalid mode, empty ca_ids with non-disabled mode, > 32 CAs, or one of the CA IDs doesn't belong to you.

401 Unauthorized

Missing auth.

403 Forbidden

Plan doesn't include the mtls entitlement (only when enabling — disabling is always allowed).

404 Not Found

Endpoint doesn't exist or belongs to another user.

500

Database error during the transaction. State is rolled back; safe to retry.

Request — enable mTLS
curl -X PUT "https://api.ngris.com/v1/endpoints/<uuid>/mtls" \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"mode": "required", "ca_ids": [7, 12]}'

Request — disable
curl -X PUT "https://api.ngris.com/v1/endpoints/<uuid>/mtls" \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"mode": "disabled", "ca_ids": []}'

Python
from ngris import Ngris

client = Ngris(api_key="<your_api_key>")
client.client_cas.update_mtls(
    "<endpoint_uuid>",
    {"mode": "required", "ca_ids": [7, 12]},
)

Response — 200 OK
{
  "endpoint_id": 184,
  "mode": "required",
  "ca_ids": [7, 12]
}

PreviousGet mTLS Config NextList Endpoint API Keys

On this page

Update mTLS Config