Update Mtls Endpoints

Update mTLS Config

PUT /v1/endpoints/{uuid}/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. mTLS works on HTTP(S) endpoints only: TCP and UDP tunnels never check client certificates.

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_uuids — without one, the tunnel-server has nothing to validate against. Maximum 32 CAs per endpoint.

Every CA in the list is resolved in your active account before anything is persisted. The mode change + CA list replacement happen in a single transaction; partial state is impossible.

Path parameters

uuid string (uuid) Req

Endpoint UUID.

Request body

mode string Req

disabled | optional | required.

ca_uuids string[] (uuid)

The uuids of the trusted client CAs (from /client-cas). Empty when mode: "disabled"; required (length ≥ 1) for optional and required. Max length 32.

Deprecated: ca_ids (integers) is still accepted until the sunset. Send ca_uuids; sending both for different sets of CAs is a 400 id_uuid_mismatch.

Response (200 OK)

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

Deprecated: until the sunset this response also carries the legacy integer endpoint_id and ca_ids fields. Don't use them; read endpoint_uuid and ca_uuids.

Errors

400 Bad Request

Invalid JSON, invalid mode, empty ca_uuids with non-disabled mode, > 32 CAs, a malformed entry in ca_uuids, or ca_ids and ca_uuids naming different CAs (id_uuid_mismatch).

401 Unauthorized

Missing auth.

403 Forbidden

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

404 Not Found

Endpoint not found in your active account, or a ca_uuids entry names no client CA you own (another account's CA reads like an unknown one).

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_uuids": ["019af8a2-4b16-70ea-8090-9f63343250c8", "019b07e7-fbab-74be-a38d-e60284dd7254"]}'

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_uuids": []}'

Python
from ngris import Ngris

client = Ngris(api_key="<your_api_key>")
client.client_cas.update_mtls(
    "<endpoint_uuid>",
    {"mode": "required", "ca_uuids": ["019af8a2-4b16-70ea-8090-9f63343250c8", "019b07e7-fbab-74be-a38d-e60284dd7254"]},
)

Response — 200 OK
{
  "mode": "required",
  "ca_uuids": ["019af8a2-4b16-70ea-8090-9f63343250c8", "019b07e7-fbab-74be-a38d-e60284dd7254"],
  "endpoint_uuid": "019bb1e4-e785-77d2-9966-c3cff31d0a0e"
}

Was this helpful?

PreviousGet mTLS Config NextList Endpoint API Keys

On this page

Update mTLS Config

Was this helpful?