Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kavachos.com/llms.txt

Use this file to discover all available pages before exploring further.

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

lib/kavach.ts
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

StrategyBehavior
evict-oldestDeletes the least-recently-used session when the cap is reached
rejectReturns 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.
List sessions (client)
const res = await fetch('/auth/sessions', {
  credentials: 'include',
});

const { sessions } = await res.json();
Response shape 
{
  "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"
    }
  ]
}
Device information is parsed from the 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.
Revoke session (client)
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.
​
trackDevice
boolean
default:"true"
Parse and store browser/OS information from the User-Agent header.
​
trackIp
boolean
default:"true"
Store the IP address of the sign-in request.
Last modified on April 18, 2026