Auth Endpoints

Update Endpoint Auth

PUT /v1/endpoints/{uuid}/settings

Configure how visitors authenticate to an endpoint at the edge — before traffic ever reaches the agent. An endpoint has exactly one of three auth modes:

none — public, no auth (the default).
basic — callers sign in as one of the endpoint's Access Control clients: with a username and password (the username_password method) and/or the client's own token, sent as Authorization: Bearer or X-Tunnel-Token (the bearer_token method).
sso — visitors sign in with Google, GitHub or your OIDC provider through the endpoint's OAuth providers. It is stored as basic with the oauth_sso method turned on, so GET /v1/endpoints/{uuid}/settings reads it back as "mode": "basic" with enabled_auth_methods.oauth_sso: true.

Any other mode returns 400. The former token mode was removed (per-caller tokens are Access Control clients), and header and cookie were never enforced. JWT validation is not an auth mode: to check JWTs your callers already send, add a jwt-validation traffic policy rule (phase on_http_request) and keep the endpoint's mode none, basic or sso. The old PUT /v1/endpoints/{uuid}/settings/jwt is retired and returns 410.

An endpoint still stored with an unsupported mode (from before these changes) refuses every request at the edge until you set none, basic or sso here.

The handler uses strict JSON decoding — unknown fields return 400. mode and enforce_https are written on every call (a missing mode means none; a missing enforce_https means false), so send both each time. session_ttl_seconds and enabled_auth_methods keep their current values when omitted, and config is merged into the existing config.

Path parameters

uuid string (uuid) Req

Endpoint UUID.

Request body

mode string Req

none | basic | sso (case-insensitive). sso is stored as basic + oauth_sso. token, header, cookie, jwt and anything else return 400.

enforce_https boolean

Redirect plaintext HTTP to HTTPS. Resets to false when omitted. Recommended true on any auth-enabled endpoint.

enabled_auth_methods object

Which sign-in methods the endpoint accepts: {"username_password": bool, "bearer_token": bool, "oauth_sso": bool}. Kept as is when omitted. With mode: "sso", oauth_sso is turned on (sending it false returns 400) and the other methods are the ones you send, else the endpoint's current ones. Turning all three off leaves the endpoint open, whatever the mode.

session_ttl_seconds int

How long a successful sign-in stays valid. Must be positive. Kept as is when omitted.

config object

For basic / sso: the login page (title, message, button_label), which paths need a sign-in (protect_all, protected_paths) and registration (self-registration and the headers forwarded after sign-in, also set by PUT …/rbac/registration-policy). Merged into the existing config.

There is no field for credentials: usernames, passwords and tokens belong to Access Control clients. Set the mode and methods here first — a client is refused a password or token whose method isn't enabled — then create the clients.

Response (200 OK)

Returns the stored settings — same shape as GET /v1/endpoints/{uuid}/settings, including endpoint_uuid.

Deprecated: until the sunset this response also carries the legacy integer endpoint_id. Don't use it; read endpoint_uuid.

Errors

400 Bad Request

Invalid JSON or unknown fields (strict decoding); a mode other than none, basic or sso (the message says what to use instead — for jwt, the jwt-validation rule); mode: "sso" with oauth_sso: false; a non-empty tokens list (it belonged to the removed token mode); or session_ttl_seconds ≤ 0.

401 Unauthorized

Missing auth.

403 Forbidden

Your role lacks endpoints:update.

404 Not Found

Endpoint doesn't exist or belongs to another account.

409 Conflict

quota_paused: the endpoint is paused over your plan's limits and is read-only.

500

Database error loading or persisting the auth policy.

Request — basic (username/password)
curl -X PUT "https://api.ngris.com/v1/endpoints/<uuid>/settings" \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "basic",
    "enforce_https": true,
    "session_ttl_seconds": 3600,
    "enabled_auth_methods": {"username_password": true, "bearer_token": false, "oauth_sso": false}
  }'

# then one Access Control client per user
curl -X POST "https://api.ngris.com/v1/endpoints/<uuid>/rbac/clients" \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"identifier": "admin", "username": "admin", "password": "MyS3cur3P@ss!"}'

Python
from ngris import Ngris

client = Ngris(api_key="<your_api_key>")
client.endpoints.update_settings("<endpoint_uuid>", {
    "mode": "basic",
    "enforce_https": True,
    "session_ttl_seconds": 3600,
    "enabled_auth_methods": {"username_password": True, "bearer_token": False, "oauth_sso": False},
})

Request — SSO (Google)
# 1. attach the provider: POST /v1/endpoints/<uuid>/oauth/providers
# 2. turn on SSO sign-in
curl -X PUT "https://api.ngris.com/v1/endpoints/<uuid>/settings" \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "sso",
    "enforce_https": true,
    "session_ttl_seconds": 86400
  }'

Response — 200 OK (SSO; the endpoint had no other method on)
{
  "endpoint_uuid": "019bb1e4-e785-77d2-9966-c3cff31d0a0e",
  "mode": "basic",
  "enforce_https": true,
  "session_ttl_seconds": 86400,
  "enabled_auth_methods": {"username_password": false, "bearer_token": false, "oauth_sso": true},
  "config": {"title": "Secure Access", "message": "Please sign in to continue.", "button_label": "Sign In", "protect_all": false, "protected_paths": []}
}

Response — 400 (mode "jwt")
{
  "error": "\"jwt\" is not supported as an endpoint auth mode (use none, basic or sso). JWTs are checked by the jwt-validation traffic policy rule: ..."
}

Was this helpful?

PreviousEndpoint Health-Check Settings NextDedicated Ports

On this page

Update Endpoint Auth

Was this helpful?