Owner: Engineering Team | Last Updated: 2026-01-30 | Status: Current
All WWAI clients authenticate using JWT (JSON Web Token) bearer tokens. The Django backend issues tokens on login and provides a refresh mechanism. For the high-level auth overview, see Authentication Architecture.
Login Request Token Usage Token Refresh
───────────── ─────────── ─────────────
POST /api/user/login/ ──► Authorization: Bearer <jwt> Every 55 minutes:
{ email, password } │ POST /api/user/refresh/
│ │ Valid for ~1 hour { refresh_token }
▼ │ │
Response: ▼ ▼
{ access_token, API Request ──► Backend New { access_token,
refresh_token } validates JWT returns data refresh_token }
| Property | Value |
|---|---|
| Type | JWT (JSON Web Token) |
| Algorithm | RS256 |
| Access Token Expiry | ~1 hour |
| Refresh Interval | Every 55 minutes (before expiry) |
| Header Format | Authorization: Bearer <jwt> |
The NextAuth.js configuration in server/auth.ts automatically refreshes tokens:
// Simplified refresh logic
async jwt({ token, user }) {
// On initial login, store tokens
if (user) {
token.accessToken = user.access_token;
token.refreshToken = user.refresh_token;
token.expiresAt = Date.now() + 60 * 60 * 1000; // 1 hour
}
// Refresh 5 minutes before expiry (at 55 min mark)
if (Date.now() < token.expiresAt - 5 * 60 * 1000) {
return token; // Still valid
}
// Refresh the token
const response = await fetch('/api/user/refresh/', {
method: 'POST',
body: JSON.stringify({ refresh: token.refreshToken })
});
const refreshed = await response.json();
token.accessToken = refreshed.access;
token.refreshToken = refreshed.refresh;
token.expiresAt = Date.now() + 60 * 60 * 1000;
return token;
}
The Chrome plugin uses a separate extension token:
extension cookie)| Scenario | HTTP Status | Action |
|---|---|---|
| Token expired | 401 | Trigger token refresh |
| Refresh token expired | 401 | Redirect to login |
| Invalid token | 401 | Clear session, redirect to login |
| Rate limited | 429 | Wait and retry (see rate limit headers) |
| Date | Author | Change |
|---|---|---|
| 2026-01-30 | Admin | Initial creation |
Prev: Authentication Architecture | Next: OAuth Providers | Up: WalterWrites