Session tokens
Passwork uses a token-based authentication model with Access Token / Refresh Token pair.
Token system overview
| Token | Purpose | Lifetime |
|---|---|---|
| Access Token | API request authentication | ~2.8 hours |
| Refresh Token | Access Token renewal | 36 hours |
Why not JWT?
Passwork tokens are random strings, not JWT. For a password manager, this approach provides higher security:
| Characteristic | Passwork tokens | JWT |
|---|---|---|
| Format | Random Base64 string | JSON with signature |
| Information in token | None | Payload with data |
| Validation | Database lookup | Signature verification |
| Token revocation | Instant (DB deletion) | Requires blacklist |
Security advantages:
-
Instant session revocation. If compromise is suspected, administrator or user can immediately terminate any session — token is deleted from database and immediately becomes invalid. JWT continues working until expiration.
-
Full session control. All active sessions are stored on server, allowing tracking devices, IP addresses, and last activity time. Administrator sees complete picture and can manage access.
-
No sensitive data in token. JWT contains payload with user information that can be read (Base64 is not encryption). Passwork tokens are simply random identifiers without any information.
-
Key compromise resistance. If JWT secret key leaks, attacker can create valid tokens for any user. With session tokens, this attack vector doesn't exist.
-
No signing secret key. JWT requires storing private key on server for token signing — another secret to protect, rotate, and control. Passwork session tokens are just random strings, no secret keys needed for generation.
Access Token
Characteristics
| Parameter | Value |
|---|---|
| Length | 256 bits |
| Format | Base64 |
| String length | ~44 characters |
| Entropy | 256 bits |
| Default lifetime | 10,000 seconds (~2.8 hours) |
Generation
Access Token is generated with cryptographically secure random number generator:
token = base64(random_bytes(32))
Validation
On each request, server:
- Extracts token (from cookie or header, depending on mode)
- Looks up token in database
- Checks lifetime
- Links request to user
Token transmission modes
Passwork uses two Access Token transmission modes depending on client type:
Browser Mode (web application)
For web application, Access Token is transmitted via HttpOnly Cookie:
| Parameter | Value |
|---|---|
| HttpOnly | Yes — inaccessible to JavaScript (XSS protection) |
| Secure | Yes — HTTPS only |
| SameSite | Strict — CSRF protection |
In this mode, browser automatically attaches cookie to each request. Access Token is not returned in response body during authentication — only in Set-Cookie header.
API Mode (desktop, extension, mobile)
For API clients, Access Token is transmitted in Authorization header:
Authorization: Bearer {access_token}
In this mode, Access Token is returned in response body during authentication, and client manages storage independently.
Mode comparison
| Parameter | Browser Mode | API Mode |
|---|---|---|
| Clients | Web application | Desktop, Extension, Mobile |
| Token transmission | HttpOnly Cookie | Authorization header |
| XSS protection | ✓ (HttpOnly) | Depends on client |
| Token management | Browser (automatic) | Client (manual) |
Refresh Token
Characteristics
| Parameter | Value |
|---|---|
| Length | 256 bits |
| Format | Base64 |
| String length | ~44 characters |
| Entropy | 256 bits |
| Default lifetime | 129,600 seconds (36 hours) |
Purpose
Refresh Token is used to obtain new Access Token without re-authentication. More on renewal process in Token rotation section.
Lifetime configuration
By user roles
Token lifetime is configured at user role level:
| Setting | Default value |
|---|---|
| Access Token lifetime | 10,000 sec (~2.8 hours) |
| Refresh Token lifetime | 129,600 sec (36 hours) |
Configuration examples
| Scenario | Access TTL | Refresh TTL |
|---|---|---|
| Standard user | 10,000 sec | 129,600 sec |
| High security | 1,800 sec (30 min) | 14,400 sec (4 hours) |
| Convenience | 28,800 sec (8 hours) | 604,800 sec (7 days) |
Session lifecycle
Complete lifecycle
T=0: Authentication. User enters credentials. Server creates Access Token (TTL: 2.8 hours) and Refresh Token (TTL: 36 hours).
T=2.8h: Access Token expired. Client sends Refresh Token. Server issues new tokens. Old Refresh Token is invalidated.
T=36h: Refresh Token expired. Re-authentication required. User enters credentials again.
Alternative scenario — Logout. User clicks "Logout". Both tokens are invalidated. Session terminated.
Token invalidation
All session tokens are invalidated on:
- User logout
- Master password change
- Administrator master password reset
Token rotation
Standard mode (applications)
For web application, browser extension, mobile and desktop apps, strict token rotation policy applies.
When refreshing session, client sends Access Token and Refresh Token simultaneously, and receives new token pair in response. This provides continuous rotation of both tokens, preventing reuse of stolen tokens.
Automation mode (API)
For DevOps tasks and automation, strict rotation is often inconvenient. Therefore, for sessions created via API token generation, alternative mode is available:
- Access Token only refresh without Refresh Token change
- Separate Refresh Token renewal when needed
This allows using long-lived Refresh Tokens in scripts and CI/CD pipelines.
Token security
Interception protection
| Threat | Protection |
|---|---|
| Network interception | HTTPS/TLS required |
| XSS attack | HttpOnly cookies (Browser Mode) |
| CSRF | CSRF Token + SameSite cookies |
CSRF Token
Purpose
CSRF Token protects against cross-site request forgery attacks. Required for all modifying operations.
Characteristics
| Parameter | Value |
|---|---|
| Size | 256 bits |
| Format | Hexadecimal (64 characters) |
| Entropy | 256 bits |
| Generator | Cryptographically secure |
Usage
CSRF Token is transmitted in header of each request:
X-CSRF-Token: {csrf_token}
Requirements by client type
| Client type | CSRF Token |
|---|---|
| Web application (Browser Mode) | ✓ Required (generated and validated automatically) |
| Browser extension | Optional (on client request) |
| Mobile application | Optional (on client request) |
| API | — (not used) |
Cookie Sign
Purpose
Optional additional protection feature for Browser Mode. Binds session to client context, protecting against cookie theft and session hijacking.
How it works
When enabled, server computes signature based on:
- Client IP address
- Browser User-Agent
- Session identifier
- Secret key (60 characters, ~357 bits entropy)
Signature is computed by formula:
cookieSign = HMAC-SHA512(IP + UserAgent + SessionID, secret)
Signature is saved in separate HttpOnly cookie and verified on each request.
Attack protection
| Attack | Protection |
|---|---|
| Session Hijacking | Stolen cookie doesn't work from different IP |
| Cookie Theft | Cookie useless without matching IP + User-Agent |
Limitations
- IP change (VPN, mobile network) requires re-authentication
- Browser update may change User-Agent
Enabling
Feature is enabled by administrator in system settings. Disabled by default for compatibility with users with dynamic IP.
Client types
Passwork distinguishes four client types with different security mechanisms:
| Feature | Web | Browser Extension | Mobile | API |
|---|---|---|---|---|
| Token transmission mode | Browser Mode | API Mode | API Mode | API Mode |
| Access Token | Cookie | Header | Header | Header |
| CSRF Token | ✓ Required | Optional | Optional | — |
| Cookie Sign | Optional | — | — | — |
| PIN code | — | ✓ Supported | — | — |
Browser Extension — only client type supporting server-side PIN code. PIN is verified on server, which opens temporary window for API use. After timeout, session is locked until PIN re-entry. On multiple incorrect attempts, server immediately terminates session. This protects against token theft — even with token compromise, attacker cannot use API without knowing PIN.
HTTP headers
Authentication headers
| Header | Description | Mode |
|---|---|---|
Authorization | Access Token (Bearer {token}) | API Mode |
Cookie | Access Token (automatic) | Browser Mode |
X-CSRF-Token | CSRF protection | All modes |
X-Master-Key-Hash | Master key hash | When needed |
Client-side token storage
Each client type implements secure token storage according to platform capabilities:
- Web application — Access Token stored in HttpOnly Cookie, inaccessible to JavaScript (XSS protection)
- Desktop and Mobile apps — tokens stored in OS secure storage with restricted access
- Browser extension — isolated browser storage used, inaccessible from web pages
Multiple sessions
Parallel sessions
Passwork supports multiple simultaneous sessions:
- User can be authenticated on multiple devices
- Each device has its own token pair
- Logout on one device doesn't affect others
Session management
User can:
- View list of active sessions
- Terminate specific session
- Terminate all sessions (except current)
Administrator can:
- Force terminate all user sessions
Configuration recommendations
High security
| Parameter | Value |
|---|---|
| Access Token | 30 minutes |
| Refresh Token | 4 hours |
- Frequent re-authentication
- Short attack window
- Suitable for critical systems
Security and convenience balance (default)
| Parameter | Value |
|---|---|
| Access Token | ~2.8 hours |
| Refresh Token | 36 hours |
- Workday without re-authentication
- Refresh Token for ~1.5 workdays
- Suitable for most organizations
Maximum convenience
| Parameter | Value |
|---|---|
| Access Token | 8 hours |
| Refresh Token | 7 days |
- Authentication once a week
- Suitable for low-risk scenarios
- Not recommended for critical data