# Roles and Permissions

Role-Based Access Control (RBAC) implementation with hierarchical permissions.

```{contents} Table of Contents
:depth: 2
:local: true
```

## Default Roles

```{eval-rst}
.. list-table::
   :header-rows: 1
   :widths: 15 50 35

   * - Role
     - Permissions
     - Typical Users
   * - **admin**
     - All permissions, user management
     - System administrators
   * - **observer**
     - Create/update observations, register data
     - Observatory operators
   * - **viewer**
     - Read-only access
     - Scientists, collaborators
   * - **service**
     - Automated operations
     - Background services
```

## Permission Model

Permissions follow pattern: `action:resource`

Examples:

- `read:observations`
- `write:observations`
- `delete:observations`
- `manage:users`
- `configure:system`

## Decorators

**Require roles**:

```python
from ccat_ops_db_api.auth import require_roles

@router.post("/admin/users")
@require_roles("admin")
async def create_user(
    user_data: UserCreate,
    current_user: User = Depends(get_current_user)
):
    # Only admins can create users
    ...
```

**Require permissions**:

```python
from ccat_ops_db_api.auth import require_permissions

@router.post("/executed_obs_units/start")
@require_permissions("write:observations")
async def start_observation(
    obs_data: ExecutedObsUnitCreate,
    current_user: User = Depends(get_current_user)
):
    # Users with write:observations permission
    ...
```

## Helper Functions

```python
from ccat_ops_db_api.auth import has_role, has_permission

if has_role(current_user, "admin"):
    # Show admin options
    pass

if has_permission(current_user, "delete:observations"):
    # Allow deletion
    pass
```

## Database Schema

```sql
CREATE TABLE user_role (
    user_id INTEGER REFERENCES "user"(id),
    role_id INTEGER REFERENCES role(id),
    PRIMARY KEY (user_id, role_id)
);

CREATE TABLE role_permission (
    role_id INTEGER REFERENCES role(id),
    permission_id INTEGER REFERENCES permission(id),
    PRIMARY KEY (role_id, permission_id)
);
```

## Next Steps

- {doc}`../../tutorials/simple-endpoints/adding-authentication` - Tutorial