OAuth Bearer Token Debug Logging

Overview

When you authenticate with BlueClerk using bearer tokens (OAuth access tokens or mobile JWTs), the system logs detailed debug information to help diagnose authentication failures. These logs include token source headers, rejection reasons, and user context - making it easier to troubleshoot API integration issues or mobile app login problems.

What Gets Logged

Successful Authentication

When a bearer token is successfully validated:

• Token source header - The X-Token-Source header value (e.g., "mobile-app", "oauth-client")
• User email - Which user the token belongs to
• Token type - OAuth access token or mobile JWT

Example log: [AUTH-DBG] Bearer success for user@example.com via mobile-app

Failed Authentication

When a bearer token is rejected:

• Rejection reason - Why the token failed (user not found, deactivated, token version mismatch)
• User email - Which user the token attempted to authenticate as
• Token version info - For JWTs, shows the token's version vs. database version when there's a mismatch

Example log: [AUTH] JWT rejected for user@example.com: tokenVersion mismatch (jwt=5 db=6)

Token Source Header

The X-Token-Source header helps identify where authentication requests come from:

• mobile-app - BlueClerk mobile app (iOS or Android)
• oauth-client - Third-party OAuth application
• api-test - API testing tool or development client

Include this header in your API requests to make troubleshooting easier:

Authorization: Bearer YOUR_ACCESS_TOKEN
X-Token-Source: your-app-name

Common Rejection Reasons

User Not Found

The user ID in the token doesn't match any account in the database. This usually means the token was issued for a deleted account or contains an invalid user ID.

User Deactivated

The account exists but has been deactivated by an admin. Deactivated users cannot authenticate even with valid tokens.

Token Version Mismatch

For mobile JWTs, the tokenVersion in the token doesn't match the tokenVersion in the database. This happens when:

• An admin resets the user's password
• The user's session was invalidated for security reasons
• The token was issued before a security update

The user must log in again to get a fresh token with the current version.

Using Logs for Troubleshooting

Finding Authentication Logs

Logs are written to your application runtime logs (Vercel, CloudWatch, etc.) with the [AUTH-DBG] or [AUTH] prefix. Search for these prefixes to filter authentication events.

Search examples:

• [AUTH-DBG] - All authentication debug logs
• [AUTH] JWT rejected - Failed JWT authentication attempts
• user@example.com - All auth events for a specific user

Debugging Failed Logins

If users report they can't log in:

1. Ask for their email address
2. Search logs for their email with [AUTH] prefix
3. Check the rejection reason - user not found, deactivated, or token version mismatch
4. Take action based on the reason:
   • Not found: Check if the account exists
   • Deactivated: Reactivate the account if appropriate
   • Token version mismatch: Ask the user to log in again

Questions

Q: What is the X-Token-Source header used for? A: It identifies where the authentication request came from (mobile app, OAuth client, etc.) to help with troubleshooting and monitoring.

Q: Why would a JWT be rejected for token version mismatch? A: The user's password was reset or their session was invalidated for security reasons. They need to log in again to get a fresh token.

Q: Are these logs visible to end users? A: No, these are server-side logs only visible to administrators with access to application runtime logs.