Skip to content
NocleyeNocleye Docs

Client ID rules

A client ID rule decides how the gateway identifies the caller of a request. The identifier is the key used by usage control: each caller has its own count.

Client ID rules are defined under Rules.ClientIDRules and bound by name with ClientIDRule on GlobalConfig, a server or a route. The closest scope wins: route, then server, then global. When no rule applies, callers are identified by IP.

Rules:
  ClientIDRules:
    by-customer-header:
      Modes: [CustomHeader]
      HeaderCustomValue: "X-Customer-Id"


    token-then-ip:
      Modes: [BearerToken, IP]


    by-query-key:
      Modes: [CustomQueryString]
      QueryStringCustomValue: "client_token"

Options

Section titled “Options”
Key Description
Modes List of ways to identify the caller. See the table below.
HeaderCustomValue Name of the header to read. Required when Modes contains CustomHeader.
QueryStringCustomValue Name of the query string parameter to read. Required when Modes contains CustomQueryString.

Modes

Section titled “Modes”
Mode Identifier
IP The caller’s IP address.
BearerToken The value of the Authorization header.
QueryStringApiKey The apiKey query string parameter, e.g. ?apiKey=value.
CustomHeader The header named in HeaderCustomValue, e.g. X-Customer-Id: value.
CustomQueryString The query string parameter named in QueryStringCustomValue, e.g. ?client_token=value.

How modes are used

Section titled “How modes are used”
  • The IP of the caller is always counted against the usage control rules, whatever the modes are.
  • Every mode in Modes that finds a value in the request is counted too. A caller therefore has one count per identifier found.
  • A mode that finds no value in the request is skipped. If none of the modes finds a value, the caller is identified by IP.

Authenticated routes

Section titled “Authenticated routes”

When an authentication method applies to a route, the caller is identified by the token (the claim named in IdClaimName), and the client ID rule is not used for that route.

Validation

Section titled “Validation”
  • An unknown mode is an error.
  • CustomHeader without HeaderCustomValue, or CustomQueryString without QueryStringCustomValue, is an error.
  • Binding a client ID rule that does not exist is an error.
  • Having no client ID rules at all is a warning: callers will be identified by IP.