# Permissions & Roles API Documentation

## Authentication
All endpoints require authentication via Bearer token in Authorization header.

## Roles Management

### List Roles
```http
GET /api/roles
```

**Query Parameters:**
- `search` (optional): Search roles by name
- `per_page` (optional): Number of items per page (default: 15)

**Response:**
```json
{
  "data": [
    {
      "id": 1,
      "name": "admin",
      "display_name": {"ar": "مدير النظام", "en": "Administrator"},
      "description": "Full system access",
      "is_system": true,
      "permissions": [...]
    }
  ],
  "meta": {...}
}
```

### Create Role
```http
POST /api/roles
```

**Body:**
```json
{
  "name": "manager",
  "display_name": {"ar": "مدير", "en": "Manager"},
  "description": "Department manager",
  "permissions": [1, 2, 3]
}
```

### Update Role
```http
PUT /api/roles/{id}
```

### Delete Role
```http
DELETE /api/roles/{id}
```

### Assign Permissions to Role
```http
POST /api/roles/{id}/permissions
```

**Body:**
```json
{
  "permissions": [1, 2, 3, 4]
}
```

## Permissions Management

### List All Permissions
```http
GET /api/permissions
```

**Query Parameters:**
- `module` (optional): Filter by module
- `resource_type` (optional): Filter by resource type

**Response:**
```json
[
  {
    "id": 1,
    "name": "opportunities.view",
    "resource_type": "page",
    "action": "view",
    "display_name": {"ar": "عرض الفرص", "en": "View Opportunities"},
    "module": "opportunities"
  }
]
```

### Get User Permissions
```http
GET /api/permissions/user
```

**Response:**
```json
["opportunities.view", "opportunities.create", "users.edit"]
```

### Get Node Permissions
```http
GET /api/permissions/nodes/{nodeId}
```

Returns all permissions (direct + inherited) for a specific system node.

### Sync Node Permissions
```http
POST /api/permissions/nodes/{nodeId}
```

**Body:**
```json
{
  "permissions": [1, 2, 3]
}
```

## User Role Assignment

### Assign Roles to User
```http
POST /api/users/{userId}/roles
```

**Body:**
```json
{
  "roles": [1, 2]
}
```

### Remove Role from User
```http
DELETE /api/users/{userId}/roles/{roleId}
```

## Permission Naming Convention

Format: `{resource}.{action}`

**Examples:**
- `opportunities.view`
- `opportunities.create`
- `hr.employees.edit`
- `system.users.manage`

## Resource Types
- `global`: System-wide permissions
- `module`: Module-level permissions
- `section`: Section-level permissions
- `page`: Page-level permissions
- `feature`: Feature-specific permissions

## Actions
- `view`: Read access
- `create`: Create new records
- `edit`: Modify existing records
- `delete`: Delete records
- `manage`: Full access (all actions)
- `approve`: Approval workflow
- `export`: Export data