How LLMInspect Uniquely Identifies Users in Tap Mode
Overview
LLMInspect offers powerful observability and traceability features, designed to help teams monitor and analyze API client interactions in real-time. When deployed in Tap Mode, LLMInspect mirrors requests from an API Gateway (like Kong) and logs detailed insights for each incoming request.
Administrators can review these requests and the identities behind them in API Analytics, part of InspectBoard, the LLMInspect observability dashboard. These insights help teams understand who made a request, from where, and under what identity—supporting auditing, debugging, and usage analysis.
Why User Identification Matters
To enable complete traceability and user-level observability, LLMInspect attempts to bind each incoming request to a uniquely identifiable user. This allows administrators to view per-user activity, filter requests by user identity, and detect suspicious or unusual usage patterns.
How User Identification Works
LLMInspect uses a multi-layered strategy to identify users from the incoming request. It follows a precedence-based protocol, where the most reliable source of user identity is used when available.
Precedence Order
LLMInspect evaluates the following sources to identify a user (in order of precedence):
-
JWT Token (
Authorization: Bearer) If the request includes a JWT token in theAuthorizationheader, LLMInspect attempts to decode it using OpenID Connect standards. The value of thepreferred_usernamefield (if present) is used as the user identifier. -
Explicit Header (
X-User-Name) If the JWT token is not present or invalid, and the request includes anX-User-Nameheader, LLMInspect uses the value of this header as the user's identity. -
Public IP from Gateway (
X-Forwarded-For) If neither JWT norX-User-Nameis provided, LLMInspect uses the client’s public IP address as seen in theX-Forwarded-For(XFF) header. This is typically set by the gateway (like Kong or APISIX) and represents the origin IP of the request. -
Fallback (
ApiClient) If all else fails, and no identifying information is available, LLMInspect groups such requests under a generic identity namedApiClient.
Summary of Identification Sources
| Source | Used As User Identity | Notes |
|---|---|---|
Authorization: Bearer <jwt> |
preferred_username claim in token |
Must follow OpenID Connect standard |
X-User-Name header |
Header value | Useful for explicit third-party integrations |
X-Forwarded-For header |
IP address | Set by Kong/APISIX Gateway; used when no user headers are provided |
| None available | ApiClient |
Default fallback |
Practical Example in Tap Mode
When Kong is integrated with LLMInspect in Tap Mode, all API traffic is mirrored to LLMInspect for inspection. Here’s how the identification process works in practice:
- A user sends a request to your API Gateway.
- Kong mirrors the request to LLMInspect using the installed plugin.
- LLMInspect checks for a JWT token or
X-User-Namein the request. - If not found, it checks the
X-Forwarded-Forheader. - The user identity is resolved using the precedence rules.
- The request and user identity are recorded and become available in API Analytics in InspectBoard.
Tips for Accurate User Tracing
- Use
X-User-Namewhen integrating with services or scripts that don’t use JWT. - Prefer JWT tokens for authentication to enable standardized user tracking.
- Monitor unidentified users labeled as
ApiClientto improve integration fidelity.
Where to See User Data
Administrators can view user data in API Analytics in InspectBoard:
- Log in to InspectBoard and open API Analytics from the left navigation.
- Use the API client selector in the Summary section to choose the user identity you want to review. The selector includes a search field.
- Choose a time range from the time range selector in the top bar.
API Analytics lets you:
- Review Messages in range and Failed validations for the selected identity
- Inspect individual requests, with their GuardRail validation results, IP address and user agent, in the Messages & validation outcomes table
- See which GuardRails are flagging requests in the Failed validations by guardrail panel
- Monitor overall API Gateway traffic, request rates and latency
- Track Data volume (leakage) to spot potential data leakage
- Search the API Gateway audit logs when investigating an issue
- Spot unusual behavior or spikes in activity
For more details, see API Analytics in the Observability Guide.
Conclusion
LLMInspect makes it easy to trace each request back to a specific user—even in mirrored Tap Mode setups. This layered identification approach ensures reliable attribution and actionable insights into how your APIs are being used.
If you have any questions or want to improve how user identity is passed in mirrored requests, please reach out to our support team.