Unauthorized: invalid token error when using expired FaunaDB login token

Resolution

The Unauthorized: invalid token error is the expected server response when a FaunaDB login token has passed its Time-to-Live (TTL) expiration. To resolve this, the client must initiate a new login flow to obtain a fresh token.

Token Lifecycle and Revocation

In FaunaDB, login tokens are distinct entities from the keys used to generate them. Because tokens are governed by their own TTL, the following behaviors apply:

• Key Deletion: Deleting the originating key does not automatically invalidate tokens already issued from that key. Those tokens remain valid until their specific TTL expires.
• Manual Revocation: To force-invalidate an active token before its TTL lapses, you must delete the corresponding Token document directly from the database using a key with sufficient administrative privileges.
• Identity Invalidation: Deleting the underlying identity document associated with the token will typically invalidate all tokens tied to that identity.

Recommended TTL Strategy for Least-Privilege

To balance operational convenience with security, implement a short-lived access token strategy:

1. Minimize TTL: Set token expiration to minutes or a few hours rather than days. This limits the window of opportunity if a token is compromised.
2. Automate Refresh: Implement a client-side interceptor that detects the Unauthorized: invalid token error and triggers a re-authentication flow automatically.
3. Layered Security: Use Attribute-Based Access Control (ABAC) predicates. Even if a token is technically valid (TTL has not expired), changing the user's role or membership predicates will immediately deny access to protected resources.

Verification Steps

To verify the revocation behavior in your specific environment (as behavior may vary between FQL versions), perform these tests:

• TTL Expiry: Generate a token with a 10-second TTL, wait 11 seconds, and confirm the Unauthorized response.
• Key Independence: Generate a token, delete the originating key, and verify that the token still allows access until its TTL expires.
• Direct Deletion: Generate a token, delete the Token document via an admin key, and verify that subsequent requests fail immediately.

Diagnostic Detail Needed: To provide a more specific API command for token deletion, please specify if you are using FQL v4 or FQL v10.