Get how the client address is determined (admin)

GET/v1/admin/deployment/client-ip

Returns where this deployment reads the client address from (security.client_ip), the proxies it trusts and which of those are wider than they need to be, the trusted proxies that forwarded recent requests, and, when recent traffic looks like it arrives through a reverse proxy the configuration does not name, what was seen and the values that would read the client instead.

The finding is judged by the replica that answers, over the requests it served most recently, and never changes what the server believes. It is deployment configuration, so only a platform role held in the main organization may read it. Requires the nauthera.insights:read scope and the insights.read permission.

GET/v1/admin/deployment/client-ip

curl 'https://auth.example.com/v1/admin/deployment/client-ip' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response

200 OK

{
  "mode": "socket",
  "trusted_proxies": [
    "string"
  ],
  "wide_trusted_proxies": [
    "string"
  ],
  "forwarding_proxies": [
    "string"
  ],
  "findings": [
    {
      "samples": 0,
      "proxied": 0,
      "peers": [
        "string"
      ],
      "suggested_mode": "socket",
      "suggested_trusted_proxies": [
        "string"
      ]
    }
  ]
}

Authorization

Bearer tokenOAuth 2.0nauthera.insights:read

The access token must carry the scope shown.

Send it in the Authorization header:

The access token, as Bearer <token> (RFC 6750 §2.1) or, for a sender-constrained token, DPoP <token> (RFC 9449 §7.1). A token minted with a cnf.jkt confirmation is only accepted together with a DPoP proof signed by that key, whichever of the two schemes carries it.

The caller must also hold the permission insights.read: Read an organization's insights and alerts.

Headers

DPoPstring
DPoP proof JWT (RFC 9449 §4). REQUIRED on a request presenting a DPoP-bound access token, and it must be signed by the key named in the token's cnf.jkt and cover this request's method and URI. The proof is read from the request itself rather than from this decoded parameter, so every protected operation is covered whether or not it declares it.

Responses

200 OKapplication/jsonThe client-address configuration and any proxy finding.
The client-address configuration and any proxy finding.
Headers
- Cache-Controlno-store
- VaryAuthorization
Body
How this deployment determines the client address.
- modeenumrequired
  Where the client address is read from. socket: the connecting peer. x-forwarded-for: X-Forwarded-For from a trusted proxy, walked right to left. header: one single-valued header from a trusted proxy.
  Possible values"socket""x-forwarded-for""header"
- trusted_proxiesarray of stringsrequired
  The trusted-proxy networks, as configured.
  at most 1024 items · each item: at most 64 characters
- wide_trusted_proxiesarray of stringsrequired
  The trusted-proxy networks wider than security.trusted_proxies_warn_prefix: every workload inside one can name its own client address.
  at most 1024 items · each item: at most 64 characters
- forwarding_proxiesarray of stringsrequired
  The trusted proxies that forwarded recent requests, each as a host prefix: what a wide trusted network can be narrowed to. Empty when none did, or more than a few.
  at most 16 items · each item: at most 64 characters
- findingsarray of objectsrequired
  The reverse proxy recent traffic shows, if any; empty when there is none.
  Each item:
  A reverse proxy the configuration does not name: most recent requests came from a few private peers that sent a client-address header while the socket address was in use, so every client behind them shares one rate-limit bucket.
  at most 1 items
  Show item attributesHide item attributes
  samplesintegerrequired
  How many recent requests the finding was judged on.
  at least 0
  proxiedintegerrequired
  How many of them came through a suspected proxy.
  at least 0
  peersarray of stringsrequired
  The suspected proxies' addresses.
  at most 16 items · each item: at most 64 characters
  suggested_modeenumrequired
  Where the client address is read from. socket: the connecting peer. x-forwarded-for: X-Forwarded-For from a trusted proxy, walked right to left. header: one single-valued header from a trusted proxy.
  Possible values"socket""x-forwarded-for""header"
  suggested_trusted_proxiesarray of stringsrequired
  Each suspected proxy's own address as a host prefix, to add to the trusted-proxy list: a range would also trust every other workload inside it.
  at most 16 items · each item: at most 64 characters
  suggested_headerstring
  The header to read, when the suggested mode is header.
  at most 64 characters
  No other properties are accepted.
- headerstring
  The header read, for mode header.
  at most 64 characters
401 Unauthorizedapplication/problem+jsonProblem details (RFC 9457) with an RFC 6750 / RFC 9449 challenge.
Problem details (RFC 9457) with an RFC 6750 / RFC 9449 challenge.
Headers
- Cache-Controlno-store
- WWW-Authenticatestring
- DPoP-Noncestring
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json). code is a stable machine-readable slug for the problem kind (it mirrors the suffix of type), so consumers can branch on it without parsing prose. errors is present on validation failures and lists every offending field.
- titlestringrequired
  Example"Request validation failed"
- statusintegerrequired
  Example400
- typestring · uri
  Example"urn:problem-type:validation_error"
- detailstring
  Example"One or more fields did not satisfy the API schema."
- codeenum
  The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing title or detail, which are English prose for logs. A problem whose status says everything the server knows carries no code.
  Show moreShow less
  validation_error is the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are the errors list — one entry per offending field — which a form renders on those fields. required and malformed are spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.
  
  Compatibility: this is a CLOSED enum, with the same cost as AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.
  Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error"
- instancestring
  Example"/introspect"
- request_idstring
  Example"8d94ed49-1caf-4ab3-9594-557142f2d023"
- trace_idstring
  Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
  Example"4bf92f3577b34da6a3ce929d0e0e4736"
- errorsarray of objects
  Field-level violations (present for validation errors).
  Each item:
  A single field-level validation violation.
  Show item attributesHide item attributes
  fieldstringrequired
  Offending field, dotted for nested bodies (e.g. child.id).
  Example"token_type_hint"
  codestringrequired
  Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
  Example"not_allowed"
  messagestringrequired
  Example"field token_type_hint must be one of [access_token, refresh_token]"
403 Forbiddenapplication/problem+jsonProblem details (RFC 9457) with an RFC 6750 / RFC 9449 challenge.
Problem details (RFC 9457) with an RFC 6750 / RFC 9449 challenge.
Headers
- Cache-Controlno-store
- WWW-Authenticatestring
- DPoP-Noncestring
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json). code is a stable machine-readable slug for the problem kind (it mirrors the suffix of type), so consumers can branch on it without parsing prose. errors is present on validation failures and lists every offending field.
- titlestringrequired
  Example"Request validation failed"
- statusintegerrequired
  Example400
- typestring · uri
  Example"urn:problem-type:validation_error"
- detailstring
  Example"One or more fields did not satisfy the API schema."
- codeenum
  The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing title or detail, which are English prose for logs. A problem whose status says everything the server knows carries no code.
  Show moreShow less
  validation_error is the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are the errors list — one entry per offending field — which a form renders on those fields. required and malformed are spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.
  
  Compatibility: this is a CLOSED enum, with the same cost as AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.
  Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error"
- instancestring
  Example"/introspect"
- request_idstring
  Example"8d94ed49-1caf-4ab3-9594-557142f2d023"
- trace_idstring
  Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
  Example"4bf92f3577b34da6a3ce929d0e0e4736"
- errorsarray of objects
  Field-level violations (present for validation errors).
  Each item:
  A single field-level validation violation.
  Show item attributesHide item attributes
  fieldstringrequired
  Offending field, dotted for nested bodies (e.g. child.id).
  Example"token_type_hint"
  codestringrequired
  Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
  Example"not_allowed"
  messagestringrequired
  Example"field token_type_hint must be one of [access_token, refresh_token]"
429 Too Many Requestsapplication/problem+jsonToo many requests.
Too many requests.
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json). code is a stable machine-readable slug for the problem kind (it mirrors the suffix of type), so consumers can branch on it without parsing prose. errors is present on validation failures and lists every offending field.
- titlestringrequired
  Example"Request validation failed"
- statusintegerrequired
  Example400
- typestring · uri
  Example"urn:problem-type:validation_error"
- detailstring
  Example"One or more fields did not satisfy the API schema."
- codeenum
  The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing title or detail, which are English prose for logs. A problem whose status says everything the server knows carries no code.
  Show moreShow less
  validation_error is the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are the errors list — one entry per offending field — which a form renders on those fields. required and malformed are spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.
  
  Compatibility: this is a CLOSED enum, with the same cost as AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.
  Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error"
- instancestring
  Example"/introspect"
- request_idstring
  Example"8d94ed49-1caf-4ab3-9594-557142f2d023"
- trace_idstring
  Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
  Example"4bf92f3577b34da6a3ce929d0e0e4736"
- errorsarray of objects
  Field-level violations (present for validation errors).
  Each item:
  A single field-level validation violation.
  Show item attributesHide item attributes
  fieldstringrequired
  Offending field, dotted for nested bodies (e.g. child.id).
  Example"token_type_hint"
  codestringrequired
  Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
  Example"not_allowed"
  messagestringrequired
  Example"field token_type_hint must be one of [access_token, refresh_token]"
Errorapplication/problem+jsonProblem details (RFC 9457) with an RFC 6750 / RFC 9449 challenge.
Problem details (RFC 9457) with an RFC 6750 / RFC 9449 challenge.
Headers
- Cache-Controlno-store
- WWW-Authenticatestring
- DPoP-Noncestring
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json). code is a stable machine-readable slug for the problem kind (it mirrors the suffix of type), so consumers can branch on it without parsing prose. errors is present on validation failures and lists every offending field.
- titlestringrequired
  Example"Request validation failed"
- statusintegerrequired
  Example400
- typestring · uri
  Example"urn:problem-type:validation_error"
- detailstring
  Example"One or more fields did not satisfy the API schema."
- codeenum
  The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing title or detail, which are English prose for logs. A problem whose status says everything the server knows carries no code.
  Show moreShow less
  validation_error is the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are the errors list — one entry per offending field — which a form renders on those fields. required and malformed are spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.
  
  Compatibility: this is a CLOSED enum, with the same cost as AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.
  Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error"
- instancestring
  Example"/introspect"
- request_idstring
  Example"8d94ed49-1caf-4ab3-9594-557142f2d023"
- trace_idstring
  Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
  Example"4bf92f3577b34da6a3ce929d0e0e4736"
- errorsarray of objects
  Field-level violations (present for validation errors).
  Each item:
  A single field-level validation violation.
  Show item attributesHide item attributes
  fieldstringrequired
  Offending field, dotted for nested bodies (e.g. child.id).
  Example"token_type_hint"
  codestringrequired
  Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
  Example"not_allowed"
  messagestringrequired
  Example"field token_type_hint must be one of [access_token, refresh_token]"

PreviousGet the threat overview

Get how the client address is determined (admin)

GET/v1/admin/deployment/client-ip

Authorization

Headers

Responses

Headers

Body

Headers

Body

Headers

Body

Body

Headers

Body

Authorization

Headers

Responses

Headers

Body

Headers

Body

Headers

Body

Body

Headers

Body