Authentication & RBAC

JWT Authentication

Planner uses JSON Web Tokens for stateless authentication:

• Access token: 15-minute lifetime, sent as Authorization: Bearer <token> header
• Refresh token: 7-day lifetime, used to obtain new access tokens

Auth Flow

1. POST /api/auth/register — create account (firstName, lastName, email, password)
2. POST /api/auth/login — receive access + refresh tokens
3. All subsequent requests include Authorization: Bearer <access_token>
4. POST /api/auth/refresh — exchange refresh token for new access token
5. POST /api/auth/logout — invalidate refresh token

Token Payload

{
  "userId": "uuid",
  "email": "user@example.com",
  "role": "user",
  "iat": 1234567890,
  "exp": 1234568790
}

Role-Based Access Control (RBAC)

The RBAC system provides granular permissions at multiple scopes.

Permission Scopes

Scope	Level	Controller Example
GLOBAL	System-wide	Admin panel, user management
ORGANIZATION	Per organization	Org settings, member management
TEAM	Per team	Team settings, member management
PROJECT	Per project	Project settings, task management
TASK	Per task	Task CRUD (controlled by project scope)
CHAT	Chat-level	Conversation management

Available Permissions (30+)

Organization (org:): create, view, edit, delete, members.view, members.invite, members.remove, members.roles, settings.view, settings.edit

Team (team:): create, view, edit, delete, members.view, members.add, members.remove, members.roles, settings.view, settings.edit

Project (project:): create, view, edit, delete, members.view, members.add, members.remove, task.create, task.view, task.edit, task.delete, task.assign, settings.view, settings.edit

Built-in Roles

Role	Level	Description
OWNER	Org/Team/Project	Full control, can delete
ADMIN	Org/Team/Project	Management of users and settings
MANAGER	Org/Team/Project	Operational management
MEMBER	Org/Team/Project	Basic access

Custom roles can be created with any combination of permissions.

Permission Evaluation

Permissions are computed from all roles a user holds:

effective_permissions = union(
  global_roles.permissions,
  org_roles.permissions,
  team_roles.permissions,
  project_roles.permissions
)

Checking Permissions in Code

Backend (NestJS):

@Permissions(['task.create', 'task.edit'])
@Controller('/projects/:projectId/tasks')

Frontend (Pinia store):

const auth = useAuthStore()
// auth.hasPermission is a computed — auto-unwrapped in template
if (auth.hasPermission('task.create')) { ... }

User Groups

User groups allow bulk role assignment. Create a group with a set of permissions, then add users to the group. All group members inherit the group's permissions.