Roles & Permissions

Aero2 uses role-based access control (RBAC). Users are assigned roles, and roles contain permissions. Each application has its own independent set of roles and permissions — roles in one application have no effect in another.

See Roles & Permissions for concepts and the Manage Roles guide for practical setup.

GET/api/rolesAdmin

Returns all roles with their associated permissions.

Response

{
  "roles": [
    {
      "id": "role-uuid",
      "name": "admin",
      "description": "Full system access",
      "is_system": true,
      "permissions": [
        {
          "id": "perm-uuid",
          "name": "users:read"
        },
        {
          "id": "perm-uuid",
          "name": "users:write"
        }
      ],
      "created_at": "2026-01-15T08:00:00Z"
    }
  ]
}

GET/api/roles/:idAdmin

Returns a specific role with its permissions.

Parameter	Type	Description
id* path	string	Role ID

Response

{
  "id": "role-uuid",
  "name": "editor",
  "description": "Can manage content",
  "is_system": false,
  "permissions": [
    {
      "id": "perm-uuid",
      "name": "users:read"
    }
  ],
  "created_at": "2026-01-15T08:00:00Z"
}

POST/api/rolesAdmin

Creates a new custom role.

Parameter	Type	Description
name* body	string	Role name (unique)
description body	string	Role description

Request

{
  "name": "editor",
  "description": "Can manage content"
}

Response

{
  "id": "role-uuid",
  "message": "Role created"
}

PUT/api/roles/:idAdmin

Updates a role's name or description. System roles cannot be modified.

Parameter	Type	Description
id* path	string	Role ID
name body	string	Role name
description body	string	Role description

Request

{
  "description": "Can manage all content"
}

Response

{
  "message": "Role updated"
}

DELETE/api/roles/:idAdmin

Deletes a custom role. System roles cannot be deleted.

Parameter	Type	Description
id* path	string	Role ID

Response

{
  "message": "Role deleted"
}

GET/api/permissionsAdmin

Returns all available permissions.

Response

{
  "permissions": [
    {
      "id": "perm-uuid",
      "name": "users:read",
      "description": "View users"
    },
    {
      "id": "perm-uuid",
      "name": "users:write",
      "description": "Create/update users"
    }
  ]
}

POST/api/roles/:id/permissionsAdmin

Adds a permission to a role.

Parameter	Type	Description
id* path	string	Role ID
permission_id* body	string	Permission ID to add

Request

{
  "permission_id": "perm-uuid"
}

Response

{
  "message": "Permission added"
}

DELETE/api/roles/:id/permissions/:permIdAdmin

Removes a permission from a role.

Parameter	Type	Description
id* path	string	Role ID
permId* path	string	Permission ID to remove

Response

{
  "message": "Permission removed"
}