Tokenzen is a lightweight, session-based token authentication toolkit for Rails.
It provides secure, encrypted access + refresh token management for any ActiveRecord model — not just User.
Tokenzen is designed to be: - Model agnostic - Multi-model compatible - Multi-device aware - Session-limited - Secure refresh-rotation enabled - Cache-backed and scalable - Lightweight - Easy to integrate
- Works with any model (Admin, Customer, Account, etc.)
- Access + Refresh token generation
- Secure refresh token rotation (replay-safe)
- Multi-device login support
- Configurable max session limit
- Automatic session revocation on password change
- Logout from all devices
- Token validation via class-level API
- Configurable expiration
- AES-256-GCM encryption of tokens
- Rails auto-loading via Railtie
Add this to your application's Gemfile: gem "tokenzen"
Then run: bundle install
Or install manually: gem install tokenzen
Include Tokenzen in any ActiveRecord model.
class Admin < ApplicationRecord
include Tokenzen::Authenticatable
tokenzen
end
You can use Tokenzen in multiple models at the same time:
class Customer < ApplicationRecord
include Tokenzen::Authenticatable
tokenzen
end
admin = Admin.first
tokens = admin.generate_tokens
# tokens => { access_token: "...", refresh_token: "..." }
This: - Creates a new session - Enforces max session limit - Stores tokens in cache - Encrypts them using AES-256 - Returns encrypted tokens
You can also validate token pair from an instance:
admin = Admin.validate_token(access_token)
# => Admin record or nil
Use the refresh token to generate a new access token:
new_tokens = Admin.rotate_tokens(refresh_token)
# returns { access_token: "...", refresh_token: "..." }
admin.logout(access_token)-> delete current session
admin.logout_all
# clears all access and refresh tokens for this record
Create an initializer:
config/initializers/tokenzen.rb
Tokenzen.configure do |config|
config.access_token_expiry = 2.days
config.refresh_token_expiry = 2.months
config.max_sessions = 3
config.secret_key = ENV["TOKENZEN_SECRET_KEY"] || Rails.application.secret_key_base
end
The gem automatically encrypts all tokens using AES-256 with this secret key.
When a user logs in: - A new session_id is created. - Secure random keys are generated for access + refresh tokens. - Tokens are stored in cache (Redis recommended). - Tokens are encrypted using AES-256-GCM. - Sessions are tracked per model record. - Oldest session is removed if max_sessions limit is reached.
Stored payload example:
{
"model" => "Admin",
"id" => 1,
"type" => "access" # or "refresh",
"session_id" => "uuid"
}
This allows Tokenzen to work with any ActiveRecord model automatically.
Tokenzen supports: - Multiple devices per user - Configurable max session limit - Automatic removal of oldest session when limit exceeded - Full session revocation
Example: If max_sessions = 3
Logging in from 4th device will revoke the oldest session.
Use Redis as your cache store for production environments:
config.cache_store = :redis_cache_store, { url: ENV["REDIS_URL"] }
Redis provides better performance and scalability for token storage.
- Ruby >= 3.0.0
- Rails >= 6.0
- ActiveRecord-backed models
- Tokens encrypted using AES-256-GCM
- Refresh tokens rotate on use
- Old refresh tokens invalidated immediately
- Sessions revocable instantly
- No tokens stored in database
- No fingerprint/device binding required
- Replay attack resistant refresh flow
- Per-device logout
- Session listing API
- Sliding expiration
- Controller helpers
- Rack middleware
- Optional JWT mode
- OAuth compatibility layer
Bug reports and pull requests are welcome at:
https://github.com/stndrk/tokenzen
Tokenzen is released under the MIT License.