JWTs are digital tokens that securely verify user identity. In Fin, each JWT confirms that a user is who they claim to be and allows encrypted communication between the client and server.

Invalid tokens or incorrect payloads can prevent successful authentication, triggering 400 errors or blocking login attempts.

Fixing 400 errors for identified user logins

A 400 error typically means the JWT is invalid or improperly created. Follow these steps to resolve it:

Use a trusted JWT library.
Generate per-user JWTs using an industry-standard library and sign them with your Messenger API Secret.
Verify the payload.
The JWT payload must include fields exactly as expected by the SDK.
- Example: Ensure the user_id field uses the correct casing and format.
Match the token to the user.
Each JWT must correspond to the correct user. Passing a token generated for another user will cause an error.

Note: When the SDK detects an invalid JWT, it blocks login attempts to protect account security. Double-check your token configuration if errors persist.

Fixing unidentified user login issues

Unidentified logins require a clean, new session. If an invalid JWT remains active, unidentified logins can fail. Try the following:

Clear previous sessions.
Log out or fully clear the existing session in the SDK.
Start a new session.
Reinitialize the login flow using:
```
Intercom.loginUnidentifiedUser()
```

This resets the session environment and ensures a conflict-free unidentified login.

Best practices

Keep sessions isolated. Always clear old sessions before starting a new login attempt.
Validate JWTs server-side. Use verification logic to confirm token integrity before sending it to the SDK.
Rotate API secrets periodically. This helps maintain security and reduce the risk of compromised tokens.
Monitor authentication logs. Reviewing failed login logs can help identify recurring JWT formatting or timing issues.

FAQs

Why is my JWT rejected even though it looks valid?

Even small mismatches (such as casing or formatting in the user_id) can make a JWT invalid. Ensure the payload structure and signing secret are exactly aligned with the SDK requirements.

Can I reuse a JWT for multiple sessions?

No. JWTs are meant for single-use or short sessions to enhance security. Always generate a new token for each login.

How do I test whether a JWT is valid?

Use a JWT decoder (such as jwt.io) to inspect payload structure and confirm it includes the correct user_id and signature.

How to troubleshoot JWT-related errors