User & Admin Role Management

Journiv includes a comprehensive role-based access control (RBAC) system that allows you to manage user permissions and administrative access. This guide covers everything you need to know about user roles, admin capabilities, and user management.

Overview

Journiv supports two user roles:

• Admin: Full access to all features, including user management capabilities
• User: Standard access to personal journaling features

The role system ensures that your Journiv instance remains secure while allowing administrators to manage users effectively.

User Roles

Admin Role

Admins have full access to the platform, including:

• All standard user features (journals, entries, media, etc.) - for their own account only
• User management (create, update, delete users)
• Role assignment and management
• Access to admin-only API endpoints
• Ability to view all users and their account information (metadata only, not journals content)

User Role

Regular users have access to:

• Personal journals and entries
• Media uploads and management
• Tags, moods, and prompts
• Personal settings and preferences
• Export and import features

Regular users cannot access administrative features or view other users' data.

First User Bootstrap

When you first set up your Journiv instance, the first user to sign up automatically becomes an admin. This ensures that you always have at least one administrator account to manage your instance.

How It Works

1. When the first user signs up (via email/password or OIDC), they are automatically assigned the Admin role
2. All subsequent users are assigned the User role by default
3. Admins can later promote other users to admin status if needed

Important Notes

• This applies to both local signups (email/password) and OIDC authentication
• The bootstrap is race-condition safe, ensuring only one user becomes the initial admin
• You cannot demote or delete the last admin in the system (security protection)

Admin Capabilities

All admin endpoints require:

• Valid JWT access token
• Admin role
• Active account status

Authentication & Authorization

How It Works

1. Authentication: Users log in with their credentials (email/password or OIDC)
2. JWT Tokens: Upon successful login, users receive access and refresh tokens
3. Role Verification: Admin endpoints check the user's role before allowing access
4. 403 Forbidden: Non-admin users receive a 403 error when attempting to access admin endpoints

Common Scenarios

Scenario 1: Setting Up a New Instance

Steps:

1. Deploy your Journiv instance
2. The first user signs up → automatically becomes admin
3. Admin creates additional user accounts as needed
4. Admin promotes trusted users to admin if necessary

Scenario 2: Promoting a User to Admin

Steps:

1. Admin lists users to find the target user's ID
2. Admin updates the user with "role": "admin"
3. User now has admin access on next login

Example:

PATCH /api/v1/admin/users/223e4567-e89b-12d3-a456-426614174001
{
  "role": "admin"
}

Scenario 3: Temporarily Disabling a User Account

Steps:

1. Admin updates the user with "is_active": false
2. User can no longer log in or access their account
3. To re-enable: Update with "is_active": true

Example:

PATCH /api/v1/admin/users/223e4567-e89b-12d3-a456-426614174001
{
  "is_active": false
}

Scenario 4: Resetting a User's Password

Steps:

1. Admin updates the user with a new password
2. User can log in with the new password
3. Recommend the user changes their password after login

Example:

PATCH /api/v1/admin/users/223e4567-e89b-12d3-a456-426614174001
{
  "password": "TemporaryPass123"
}

Scenario 5: Managing Multiple Admins

Best Practice:

1. Start with one admin (first user)
2. Create a second admin account for redundancy
3. Never operate with only one admin (backup protection)
4. When removing an admin, ensure at least one admin remains

Security Considerations

Built-in Protections

1. Last Admin Protection: Cannot delete or demote the last admin
2. Authentication Required: All admin endpoints require valid JWT tokens
3. Role Verification: Endpoints verify admin role on every request
4. Account Status: Inactive users cannot access the system
5. Audit Logging: All admin actions are logged with timestamps

Potential Risks

⚠️ Permanent Data Loss: User deletion is irreversible - always confirm before deleting

⚠️ Privilege Escalation: Only promote trusted users to admin

⚠️ Account Takeover: Protect admin credentials carefully

⚠️ Session Management: Ensure JWT tokens are properly secured

Troubleshooting

"Admin access required" Error

Problem: Getting 403 Forbidden when accessing admin endpoints

Solutions:

• Verify your account has admin role (check with another admin)
• Ensure you're using a valid, non-expired access token
• Check that your account is active (is_active: true)
• Verify you're hitting the correct endpoint URL

"Cannot delete the last admin" Error

Problem: Unable to delete or demote an admin user

Solutions:

• Promote another user to admin first
• Ensure at least one other admin exists in the system
• This is a security protection. At least one admin must always exist

"Email already registered" Error

Problem: Cannot create user with specified email

Solutions:

• Email addresses must be unique
• Check if user already exists in the system
• Consider using a different email or updating the existing user instead

User Cannot Log In After Password Reset

Problem: User reports password not working after admin reset

Solutions:

• Verify the password meets requirements (8+ chars, letters + numbers)
• Check that account is active (is_active: true)
• Ensure user is using the new password, not the old one
• Try resetting the password again

FAQ

Q: Can I have multiple admins?

A: Yes! You can promote as many users to admin as needed.

Q: What happens if I delete the last admin?

A: The system prevents it, you cannot delete or demote the last admin.

Q: Can users self-promote to admin?

A: No, only existing admins can promote users to admin.

Q: Are OIDC users different from local users?

A: OIDC users authenticate via external providers, but have the same role capabilities as local users. Admins can manage both types equally.

Q: Can I recover a deleted user?

A: No, user deletion is permanent and irreversible. Always export data before deleting if needed.

Q: How do I create users when signup is disabled?

A: Admins can create users via the admin API regardless of signup settings. When DISABLE_SIGNUP=true, all automatic user creation is blocked (including OIDC auto-provisioning), but admins can still manually create accounts. Existing users can still log in or link their accounts via OIDC.

Q: Can Admins see other users' journals?

A: No, Admins can only see the user list (metadata only, not journal content).

Q: What's the difference between deleting and deactivating?

A: Deactivating (is_active: false) temporarily blocks access but preserves data. Deleting permanently removes all user data.

Related Documentation

• Authentication & OIDC Setup - Authentication configuration
• Security Best Practices - Security recommendations
• Environment Variables - Configuration options