Roles & Permissions

Aero2 uses Role-Based Access Control (RBAC) to manage what users can do. Users are assigned roles, and roles contain permissions.

How It Works

User → has Roles → contain Permissions

A user can have multiple roles. Each role can have multiple permissions. Permissions are checked when accessing admin API endpoints.

System Roles

Aero2 comes with two built-in system roles that cannot be modified or deleted:

Bootstrap Admin

When an application is first set up, the first user whose email matches the configured bootstrap email is automatically assigned the admin role. This is how you set up the initial administrator.

Custom Roles

You can create custom roles via the Admin API to implement fine-grained access control:

# Create a role
curl -X POST https://{your-app}.yourdomain.com/api/roles \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "editor", "description": "Can view users and audit logs"}'
 
# Add permissions to it
curl -X POST https://{your-app}.yourdomain.com/api/roles/<role_id>/permissions \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{"permission_id": "<users_read_permission_id>"}'
 
# Assign it to a user
curl -X POST https://{your-app}.yourdomain.com/api/users/<user_id>/roles \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{"role_id": "<role_id>"}'

Permissions

Permissions follow a resource:action naming convention:

API Reference

See Roles & Permissions API for the complete endpoint reference and Manage Roles guide for practical examples.