OAuth Bearer Token Authentication

Overview

BlueClerk's OAuth 2.0 implementation lets third-party applications authenticate API requests using bearer tokens. After completing the authorization flow and exchanging an authorization code for an access token, clients include the token in the Authorization header of each API request. The system automatically enforces test client isolation to prevent test tokens from accessing production data.

BlueClerk also supports mobile app authentication via JWT tokens signed with the platform's AUTH_SECRET. Mobile JWTs include user ID, email, role, company info, and a tokenVersion field for revocation support.

How Authentication Works

Making Authenticated Requests

After obtaining an access token from the token endpoint:

1. Include the token in the Authorization header of your API request
2. Format: Authorization: Bearer YOUR_ACCESS_TOKEN
3. BlueClerk verifies the token and extracts user context
4. Your request is processed with the authenticated user's permissions

Mobile JWT Authentication

Mobile apps authenticate using JWT tokens instead of OAuth:

1. User signs in via the mobile app
2. Server generates a JWT signed with AUTH_SECRET containing:
   • User ID, email, name, role
   • Company ID and details
   • tokenVersion (for revocation)
3. Mobile app includes the JWT in the Authorization header: Bearer JWT_TOKEN
4. Server verifies the JWT signature using AUTH_SECRET
5. Server checks tokenVersion against the database to ensure token hasn't been revoked
6. Server checks user.isActive to ensure account is still active

JWT Rejection Cases

Mobile JWT authentication can fail in three cases (all logged with diagnostic info):

1. User not found - The user ID in the JWT doesn't exist in the database
2. User deactivated - The user's isActive flag is false
3. Token revoked - The tokenVersion in the JWT doesn't match the database value

When any of these occur, the request is rejected with a 401 Unauthorized response and the reason is logged for debugging.

Token Types

OAuth Access Tokens

• Used by: Third-party integrations and public API clients
• Format: Opaque string stored in database
• Verification: Database lookup
• Expiration: 1 hour (configurable)
• Refresh: Use refresh token to get new access token

Mobile JWT Tokens

• Used by: BlueClerk mobile apps (iOS/Android)
• Format: JWT signed with AUTH_SECRET
• Verification: Signature validation + database checks
• Expiration: Configurable (typically 30 days)
• Revocation: Increment tokenVersion in database

Security Features

Test Client Isolation

When authenticating with a test OAuth client:

• Only test company data is accessible - production data is filtered out
• isInternal flag enforced - test clients can only see isInternal=true records
• Prevents data leakage during integration testing

Token Version Revocation

Mobile JWTs support instant revocation:

• Each user has a tokenVersion counter in the database
• Incrementing tokenVersion invalidates all existing JWTs for that user
• Useful for: logout, password reset, security events
• No token blacklist needed - revocation is stateless

Error Handling

Common OAuth Errors

• 401 Unauthorized - Token is missing, invalid, or expired
• 403 Forbidden - Token is valid but lacks required permissions
• 404 Not Found - Resource doesn't exist or isn't accessible with this token

Mobile JWT Errors

All mobile JWT failures return 401 Unauthorized with a logged reason:

• "user not found" - User ID in JWT doesn't exist
• "deactivated" - User account is inactive
• "tokenVersion mismatch (jwt=X db=Y)" - Token has been revoked

Check server logs for [AUTH] JWT rejected for {email} messages to diagnose mobile auth issues.

Best Practices

OAuth Clients

• Store access tokens securely - Never expose them in client-side code
• Refresh before expiration - Use refresh tokens proactively
• Handle 401 errors gracefully - Re-authenticate when tokens expire

Mobile Apps

• Check isActive before generating JWTs - Don't issue tokens to deactivated users
• Increment tokenVersion on security events - Password changes, logout, account compromise
• Log rejection reasons - Use diagnostic logs to debug auth failures

Questions

Q: What's the difference between OAuth and mobile JWT auth? A: OAuth is for third-party integrations and uses database-stored tokens. Mobile JWT auth is for BlueClerk's native apps and uses cryptographically signed tokens. Both use the same Authorization: Bearer header format.

Q: How do I revoke a mobile user's tokens? A: Increment their tokenVersion field in the database. All existing JWTs will be rejected on the next request.

Q: Why does my mobile JWT keep getting rejected? A: Check the server logs for [AUTH] JWT rejected messages. The three cases are: user not found, user deactivated, or tokenVersion mismatch. The log will tell you which one.

Q: Can I use the same token for multiple API requests? A: Yes - OAuth access tokens and mobile JWTs are valid until they expire or are revoked. Reuse them across requests to avoid unnecessary authentication overhead.