By default, KavachOS allows unlimited concurrent sessions per user. The multi-session module adds a cap, a configurable overflow strategy, and endpoints for listing and revoking sessions, useful for building an “active devices” settings page.
Setup
import { createKavach } from 'kavachos';
import { multiSession } from 'kavachos/auth';
const kavach = await createKavach({
database: { provider: 'postgres', url: process.env.DATABASE_URL! },
secret: process.env.KAVACH_SECRET!,
baseUrl: 'https://auth.example.com',
plugins: [
multiSession({
maxSessions: 5,
overflow: 'evict-oldest',
}),
],
});
Overflow strategies
| Strategy | Behavior |
|---|
evict-oldest | Deletes the least-recently-used session when the cap is reached |
reject | Returns 429 with code SESSION_LIMIT_REACHED, new sign-in fails |
List sessions
GET /auth/sessions
Returns all active sessions for the authenticated user. Useful for building an “active devices” UI.
const res = await fetch('/auth/sessions', {
credentials: 'include',
});
const { sessions } = await res.json();
{
"sessions": [
{
"id": "ses_abc123",
"current": true,
"createdAt": "2025-06-01T10:00:00.000Z",
"expiresAt": "2025-06-08T10:00:00.000Z",
"device": {
"browser": "Chrome",
"os": "macOS",
"type": "desktop"
},
"ipAddress": "203.0.113.1"
}
]
}
User-Agent header at sign-in time. IP addresses are stored as-is, apply your own masking if required.
Revoke a session
DELETE /auth/sessions/:id
Revokes a specific session. Users can revoke any of their own sessions, including the current one.
await fetch(`/auth/sessions/${sessionId}`, {
method: 'DELETE',
credentials: 'include',
});
Revoke all other sessions
DELETE /auth/sessions
Revokes all sessions for the user except the current one. Useful for “sign out everywhere else” buttons.
Sign out all other devices (client)
await fetch('/auth/sessions', {
method: 'DELETE',
credentials: 'include',
});
Configuration reference
maxSessions
number
default:"0 (unlimited)"
Maximum concurrent sessions per user. Set to 0 for unlimited.
overflow
'evict-oldest' | 'reject'
default:"'evict-oldest'"
What to do when a new sign-in would exceed maxSessions.
Parse and store browser/OS information from the User-Agent header.
Store the IP address of the sign-in request.
