Authentication
Secure your CatCMS application with JWT authentication and role-based access control. [object Object]
Overview
CatCMS uses JWT (JSON Web Tokens) for authentication with:
- 24-hour token expiration
- HTTP-only cookie storage for web clients
- Bearer token support for API clients
- KV-based token caching (5-minute TTL)
- Role-based access control (RBAC)
- Permission system for fine-grained access
JWT Tokens
Secure, stateless authentication with automatic expiration
User Roles
Admin, Editor, Author, and Viewer roles with different permissions
Fast Verification
KV cache for sub-millisecond token verification
Secure by Default
HTTP-only cookies, CSRF protection, and rate limiting
JWT Authentication
Login
/auth/login curl -X POST http://localhost:8787/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "admin@catcms.app",
"password": "admin123"
}'const response = await fetch('http://localhost:8787/auth/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
email: 'admin@catcms.app',
password: 'admin123',
}),
})
const { user, token } = await response.json()Login Request
Response (200 OK):
{
"user": {
"id": "admin-user-id",
"email": "admin@catcms.app",
"username": "admin",
"firstName": "Admin",
"lastName": "User",
"role": "admin"
},
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}Using the Token
Include the token in the Authorization header for authenticated requests:
curl http://localhost:8787/admin/content \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."const response = await fetch('http://localhost:8787/admin/content', {
headers: {
Authorization: `Bearer ${token}`,
},
})Authenticated Request
For browser-based applications, the token is automatically stored as an HTTP-only cookie named auth_token.
User Management
User Registration
/auth/register curl -X POST http://localhost:8787/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "securepassword123",
"username": "newuser",
"firstName": "John",
"lastName": "Doe"
}'const response = await fetch('http://localhost:8787/auth/register', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
email: 'user@example.com',
password: 'securepassword123',
username: 'newuser',
firstName: 'John',
lastName: 'Doe',
}),
})
const { user, token } = await response.json()Register User
RBAC
User Roles
CatCMS supports four built-in roles:
- Name
admin- Type
- string
- Description
Full system access. Can manage users, content, settings, and plugins.
- Name
editor- Type
- string
- Description
Content management. Can create, edit, publish, and delete content.
- Name
author- Type
- string
- Description
Content creation. Can create and edit own content, but not publish.
- Name
viewer- Type
- string
- Description
Read-only access. Can view content but not modify.
Middleware
Protect routes with authentication and role-based middleware:
// Require authentication
app.use('/admin/*', requireAuth())
// Require specific role
app.use('/admin/*', requireRole(['admin', 'editor']))
// Require permission
app.use('/admin/settings/*', requirePermission('manage:settings'))
// Optional authentication
app.use('/api/*', optionalAuth())