Managing Roles

This guide covers two tasks: adding a new role to the access control system, and recovering admin access when locked out.

Adding a New Role

Update roles.ts
src/roles/roles.ts
```
export const USER_ROLES = {
    ADMIN: 'admin',
    EDITOR: 'editor',
    VIEWER: 'viewer', // Add new role
};
```
USER_ROLES is the single source of truth for role strings. Everything else in the codebase imports from here — changing a string in one place updates it everywhere.
Update permissions.ts
src/roles/permissions.ts
```
rolePermissions.viewer = [
    'view_content',
    // Add more permissions as needed
];
```
Each key in rolePermissions maps a role to the list of permission constants it holds. requirePermission checks this map at request time.
Assign the role

The role is now available in the users collection. Go to /admin → Users and assign the new role to a user.

Use constants (USER_ROLES.VIEWER) instead of strings ('viewer') for type safety throughout your code.

Locked out of the admin panel? Use the recovery endpoint to regain access.

Set the recovery secret
.env
```
PAYLOAD_ADMIN_RECOVERY_SECRET=your-secure-secret-here
```
The endpoint is disabled when this variable is not set, so it cannot be called accidentally in production.
Call the recovery endpoint
Terminal window
```
curl -X POST http://localhost:3000/admin-recovery \
  -H "Content-Type: application/json" \
  -d '{"secret": "your-secure-secret-here", "email": "your@email.com", "password": "newpassword"}'
```
If the email exists, the user’s role is updated to admin. If it does not exist, a new admin user is created with the supplied password.

Keep PAYLOAD_ADMIN_RECOVERY_SECRET out of version control. The endpoint creates users if they do not exist.

See Roles & Permissions for the full reference.