Client Identification

Client identification enables Nexus to recognize and differentiate between individual users or clients. This is essential for features like per-user token rate limiting, user-specific metrics, and tiered access control.

Enable client identification in your nexus.toml:

[server.client_identification]
enabled = true

# Choose one method to extract client ID
client_id.jwt_claim = "sub"  # Extract from JWT token claim
# OR
client_id.http_header = "x-client-id"  # Extract from HTTP header

Nexus can extract the client identifier from two sources:

Extract the client ID from a JWT token claim. This requires OAuth2 to be configured:

[server.client_identification]
enabled = true
client_id.jwt_claim = "sub"  # Common claims: "sub", "email", "user_id"

The JWT token should be provided in the Authorization header:

curl -H "Authorization: Bearer <jwt-token>" http://localhost:8000/llm/v1/chat/completions

Extract the client ID from a custom HTTP header. Only use this in trusted, private networks:

[server.client_identification]
enabled = true
client_id.http_header = "x-client-id"

The client ID should be provided in the specified header:

curl -H "X-Client-ID: user-123" http://localhost:8000/llm/v1/chat/completions

Configure user groups to implement tiered access control:

[server.client_identification]
enabled = true
client_id.jwt_claim = "sub"

# Extract group/tier information
group_id.jwt_claim = "plan"  # JWT claim containing user's plan/tier
# OR
group_id.http_header = "x-user-tier"  # HTTP header with tier info

# Define allowed groups (required when group_id is configured)
[server.client_identification.validation]
group_values = ["free", "pro", "enterprise"]

1. If you configure group_id, you must define group_values in the validation section
2. Groups not in group_values will result in a BAD REQUEST error
3. Users without a group use default limits

Client identification enables per-user rate limiting, allowing you to set different token limits for each user tier. For detailed configuration, see the LLM Rate Limiting documentation.

Here's an example showing client identification with OAuth2 and tiered access:

# OAuth2 configuration
[server.oauth]
url = "https://auth.example.com/.well-known/jwks.json"
expected_issuer = "https://auth.example.com"
expected_audience = "nexus-api"

# Client identification
[server.client_identification]
enabled = true
client_id.jwt_claim = "sub"        # User ID from JWT
group_id.jwt_claim = "subscription" # User's subscription tier

[server.client_identification.validation]
group_values = ["free", "pro", "enterprise"]

This configuration extracts user identity from JWT tokens and assigns them to tiers. These tiers can then be used with rate limiting and other features.

• Most secure option for production environments
• Requires proper OAuth2 configuration
• Claims are cryptographically verified
• Cannot be spoofed by clients

• Only use in private, trusted networks
• Can be easily spoofed if exposed to public internet
• Suitable for internal services behind a reverse proxy
• Consider using mutual TLS for additional security

• Verify the JWT token contains the specified claim
• Check that the HTTP header name matches exactly (case-sensitive)
• Ensure OAuth2 is properly configured if using JWT claims
• Check logs for parsing errors

• Ensure all possible group values are listed in group_values
• Verify the group claim/header contains a valid value
• Check for typos in group names
• Review logs for validation details

• Confirm client identification is enabled
• Verify the client ID is being extracted correctly
• Check that group configuration matches rate limit groups
• Ensure rate limiting storage is properly configured

1. Use JWT claims in production for security
2. Define all possible groups in validation
3. Start with conservative limits and adjust based on usage
4. Monitor per-user metrics to optimize limits
5. Document tier differences for users
6. Implement graceful degradation when limits are reached
7. Use consistent group names across configuration

• Configure LLM Token Rate Limiting per user
• Set up CORS for browser clients
• Enable CSRF Protection for additional security