Permissions & Roles

CutX uses a hierarchical role system with granular permissions and full audit logging for all admin actions.

Roles

Role	Level	Description
`user`	0	Standard user — can manage own resources
`admin`	1	Platform admin — can manage users, jobs, credits
`owner`	2	Platform owner — full access including billing and settings

Higher roles inherit all permissions from lower roles. An owner can do everything an admin can do, plus owner-only actions.

Permissions

Admin Permissions (level 1+)

Permission	Description
`admin.access`	Access the admin dashboard
`admin.stats`	View platform-wide statistics
`admin.users.view`	View all user accounts
`admin.users.grant_credits`	Add bonus credits to any user
`admin.users.set_role`	Change user roles (within hierarchy)
`admin.users.suspend`	Suspend or unsuspend users
`admin.jobs.view`	View all generation jobs
`admin.jobs.refund`	Refund credits for any job
`admin.jobs.retry`	Retry failed/expired jobs
`admin.jobs.cancel`	Cancel active jobs

Owner Permissions (level 2 only)

Permission	Description
`admin.settings`	Modify platform settings
`admin.billing`	Access billing and revenue data
`admin.roles`	Manage role definitions
`admin.dangerous`	Destructive operations (data purge, etc.)

Hierarchical Rules

Role Assignment

Users can only assign roles below their own level
Admins can set users to user or admin
Only owners can promote someone to admin
No one can self-promote

User Suspension

Admins can suspend users with role user
Owners can suspend users with role user or admin
No one can suspend an owner
Suspended users cannot log in or make API calls

Permission Checks

The requirePermission() middleware validates permissions before processing requests:

GET /api/admin/users
Authorization: Bearer <token>

If the user lacks admin.users.view, they receive:

{
  "error": "Forbidden",
  "message": "Missing permission: admin.users.view"
}

User Statuses

Status	Description
`active`	Normal account, full access
`suspended`	Temporarily blocked, can be reinstated
`banned`	Permanently blocked

Audit Logging

Every admin action is recorded in admin_audit_log:

{
  "id": "uuid",
  "admin_id": "uuid",
  "action": "user.grant_credits",
  "target_type": "user",
  "target_id": "uuid",
  "details": {
    "amount": 100,
    "reason": "Support compensation"
  },
  "ip_address": "203.0.113.42",
  "created_at": "2026-03-09T..."
}

Logged Actions

Action	Description
`user.grant_credits`	Admin added credits to a user
`user.set_role`	Admin changed a user’s role
`user.suspend`	Admin suspended a user
`user.unsuspend`	Admin reinstated a user
`job.refund`	Admin refunded credits for a job
`job.retry`	Admin retried a failed job
`job.cancel`	Admin canceled an active job

Audit logs are append-only — they cannot be modified or deleted through the application. Each entry includes the admin’s user ID and IP address for accountability.