Guest Tokens

Guest tokens provide anonymous user sessions, enabling features like shopping carts, wishlists, or personalized content without requiring login.

Overview#

Guest tokens work transparently alongside user tokens:

• Automatically created when no auth token exists
• Stored in a separate cookie from user tokens
• Seamlessly upgraded to user tokens on login
• Configurable credentials for your backend

Configuration#

Enable guest tokens in your proxy:

Backend Setup#

Your backend needs a guest authentication endpoint:

Endpoint#

Expected Response#

Custom Response Format#

If your backend uses a different format:

How Guest Tokens Work#

Creation Flow#

On API routes the new token is also forwarded downstream on that same request via the x-refreshed-token header, so an API client running in the route handler can use it immediately instead of waiting for the next request.

Token Priority#

When both tokens exist:

/api/auth/login is bypassed by the proxy by default (see authApi.bypassPaths), so the guest cookie is not cleared during the login request itself. It is cleared on the next request that isn't bypassed and carries a valid user token.

Detecting Guest Users#

In Proxy (afterAuth)#

In Server Components#

In Client Components#

Guest to User Upgrade#

When a guest user logs in:

Backend Considerations#

Your backend should handle guest-to-user data migration:

Guest Token Expiration#

Guest tokens typically have shorter lifespans:

When expired, a new guest token is automatically created.

Use Cases#

Shopping Cart#

Content Personalization#

Rate Limiting by Session#

Disabling Guest Tokens#

For apps that require login:

Security Considerations#

Separate Credentials#

Always use dedicated guest credentials:

Limited Permissions#

Your backend should give guest tokens minimal permissions:

Don't Store Sensitive Data#

Guest sessions should not store:

• Personal information
• Payment details
• Sensitive preferences

Instead, require login for sensitive operations.