Settings Jwt Endpoints

Update JWT Auth

PUT /v1/endpoints/{id}/settings/jwt

Configure JWT-bearer authentication for an endpoint. When enabled, every incoming request must present a valid JWT in the Authorization: Bearer <token> header — the platform fetches the IdP's public keys from the configured jwks_url, verifies the signature, and checks iss/aud claims against the configured values.

Successful verification optionally maps JWT claims into X-* headers passed to the agent (configured via claim_headers) — useful for stamping X-User-Id, X-Tenant-Id on every request without the upstream having to verify the token itself.

Layered with the main auth mode — JWT validation runs after the mode (basic/oauth/...) succeeds, so you can require both. Set enabled: false to disable without losing the configuration; the JWKS URL stays in the database for next time.

Path parameters

id string (uuid) Req

Endpoint UUID.

Request body

enabled boolean

true to start enforcing JWT verification. When true, jwks_url is required.

jwks_url string

JWKS URL of the IdP (e.g. https://idp.example.com/.well-known/jwks.json). The platform refetches keys periodically and at signature-verification failure to handle key rotation.

issuer string

Expected iss claim. Empty = don't enforce.

audience string

Expected aud claim. Empty = don't enforce.

claim_headers string (json)

JSON-encoded mapping of JWT claim → HTTP header (e.g. '{"sub": "X-User-Id", "email": "X-User-Email"}'). Stamped on the request before forwarding to the agent.

Response (200 OK)

Empty body on success.

Errors

400 Bad Request

Unknown body fields (strict decoding), invalid JSON, or enabled: true without jwks_url.

401 Unauthorized

Missing auth.

404 Not Found

Endpoint doesn't exist or belongs to another user.

500

Database error.

Request
curl -X PUT "https://api.ngris.com/v1/endpoints/<uuid>/settings/jwt" \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "jwks_url": "https://idp.example.com/.well-known/jwks.json",
    "issuer": "https://idp.example.com",
    "audience": "ngris-clients",
    "claim_headers": "{\"sub\": \"X-User-Id\", \"email\": \"X-User-Email\"}"
  }'

Python
import json
from ngris import Ngris

client = Ngris(api_key="<your_api_key>")
client._put_raw("/endpoints/<endpoint_uuid>/settings/jwt", {
    "enabled": True,
    "jwks_url": "https://idp.example.com/.well-known/jwks.json",
    "issuer": "https://idp.example.com",
    "audience": "ngris-clients",
    "claim_headers": json.dumps({"sub": "X-User-Id", "email": "X-User-Email"}),
})

Response — 200 OK

PreviousGet Endpoint Settings NextUpdate Webhook Auth Settings

On this page

Update JWT Auth