Auth & Security

Notty CMS provides two independent authentication systems, role-based access control, and machine-to-machine API tokens.

Authentication Systems

Admin Auth

Admin users manage content through the admin panel and API. They have roles: super-admin, admin, editor.

Login:

curl -X POST http://localhost:2102/api/admin/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "admin@example.com",
    "password": "your-password"
  }'

Response:

{
  "success": true,
  "data": {
    "token": "eyJhbGci...",
    "user": {
      "id": 1,
      "email": "admin@example.com",
      "username": "admin",
      "role": "super-admin"
    }
  }
}

Other admin auth endpoints:

Method	Path	Description
POST	/api/admin/auth/register	Create another admin user (super-admin only)
POST	/api/admin/auth/refresh	Refresh JWT token
GET	/api/admin/auth/me	Get current admin info
POST	/api/admin/auth/logout	Logout

Content User Auth

Separate authentication for frontend users of your application (readers, subscribers, customers).

Register a user:

curl -X POST http://localhost:2102/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "username": "john",
    "password": "secure-password"
  }'

New users get the authenticated role automatically.

Login:

curl -X POST http://localhost:2102/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "user@example.com",
    "password": "secure-password"
  }'

Other user auth endpoints:

Method	Path	Description
POST	/api/auth/refresh	Refresh token
GET	/api/auth/me	Get current user
POST	/api/auth/forgot-password	Request password reset
POST	/api/auth/reset-password	Reset with token

Password Reset Flow

1. User requests a reset:

curl -X POST http://localhost:2102/api/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{ "email": "user@example.com" }'

2. In development and test environments, the token is returned in data.resetToken. In production, you should deliver it via your email flow.

3. User resets the password:

curl -X POST http://localhost:2102/api/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "reset-token-from-response-or-email",
    "password": "new-secure-password",
    "passwordConfirmation": "new-secure-password"
  }'

OAuth

Notty supports social login via Google, GitHub, Facebook, and VK.

Setup

1. Register an OAuth application with the provider (see OAuth Setup (../../packages/server/docs/OAUTH.md в исходном проекте)).

2. Add credentials to .env:

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

3. Direct users to the provider endpoint:

GET http://localhost:2102/api/auth/google

4. The provider redirects back to /api/auth/google/callback with a JWT token.

If a user with that email already exists, they are logged in. Otherwise, a new user is created with the authenticated role.

Roles & Permissions

Built-in Roles

Role	Description
super-admin	Full access to everything. Cannot be restricted.
admin	Manages content, schemas, users. Can be customized.
editor	Content editing only. No schema or user management.

Managing Roles via API

List roles:

curl http://localhost:2102/api/admin/roles \
  -H "Authorization: Bearer $TOKEN"

Create a custom role:

curl -X POST http://localhost:2102/api/admin/roles \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "reviewer",
    "description": "Can read and comment on content",
    "type": "custom",
    "permissions": {
      "content": {
        "article": { "read": true, "create": false, "update": false, "delete": false },
        "page": { "read": true }
      },
      "media": { "read": true, "write": false, "delete": false }
    }
  }'

Permission Actions

Action	Description
read	View entries
create	Create new entries
update	Modify existing entries
delete	Remove entries
publish	Publish/unpublish entries

Permissions are checked per content type. An editor can have full access to article but read-only access to page.

API Tokens

API tokens provide machine-to-machine access without user credentials. Use them for CI/CD pipelines, external services, and automated scripts.

Create a Token

curl -X POST http://localhost:2102/api/admin/api-tokens \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI Pipeline",
    "description": "Used by GitHub Actions to publish content",
    "scopes": ["content:read", "content:write", "content:publish"]
  }'

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "CI Pipeline",
    "token": "nk_abc123def456...",
    "scopes": ["content:read", "content:write", "content:publish"]
  }
}

The full token value is returned only once at creation. Store it securely.

Use a Token

curl http://localhost:2102/api/content/article \
  -H "Authorization: Bearer nk_abc123def456..."

Available Scopes

Scope	Description
content:read	Read content entries
content:write	Create and update content
content:delete	Delete content
content:publish	Publish/unpublish
media:read	View media files
media:write	Upload media
media:delete	Delete media
webhooks:read	View webhooks
webhooks:write	Manage webhooks
admin:*	Full admin access

Token Management

Method	Path	Description
GET	/api/admin/api-tokens	List all tokens
POST	/api/admin/api-tokens	Create token
DELETE	/api/admin/api-tokens/:id	Revoke token
POST	/api/admin/api-tokens/:id/regenerate	Rotate token
GET	/api/admin/api-tokens/scopes	List available scopes

JWT Configuration

Configure JWT behavior in notty.config.ts or via environment variables:

// notty.config.ts
export default defineConfig({
  jwt: {
    secret: process.env.JWT_SECRET,
    expiresIn: '7d', // Token expiry
  },
});

Setting	Env Variable	Default	Description
JWT Secret	JWT_SECRET	auto (dev)	Required in production
Expiry	JWT_EXPIRES_IN	7d	Token lifetime

In production, missing or weak JWT_SECRET causes a fatal startup error.

Security Checklist for Production

• Set NODE_ENV=production
• Set a strong JWT_SECRET (32+ random characters)
• Use PostgreSQL or MySQL (not SQLite)
• Store database credentials in env vars, not config files
• Restrict CORS origins (not ["*"])
• Enable rate limiting
• Put OAuth secrets in env vars only
• Add .env to .gitignore
• Use HTTPS in production
• Review API token scopes (principle of least privilege)