User - Roles

Base URL: https://your-domain.com

Admin endpoints for managing user roles and permissions. All endpoints require admin authentication.

---

Fetch All Roles

Retrieve all roles configured in the system.

Property	Value
Endpoint	Fetch All Roles
Method	GET
URL	/api/v1/roles
Authentication	Bearer Token

Request Headers:

Header	Value	Required
Accept	application/json	Yes
Authorization	Bearer your-auth-token	Yes

Query Parameters:

Parameter	Type	Required	Description
isp_id	integer	Yes	ISP ID
branch_id	integer	Yes	Branch ID
user_id	integer	Yes	User ID

Success Response (200 OK):

{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "Admin",
            "user_count": 2,
            "is_system": true
        },
        {
            "id": 2,
            "name": "Staff",
            "user_count": 10,
            "is_system": false
        }
    ]
}

---

Fetch Role

Retrieve details of a specific role including permissions.

Property	Value
Endpoint	Fetch Role
Method	GET
URL	/api/v1/roles/{id}
Authentication	Bearer Token

Success Response (200 OK):

{
    "success": true,
    "data": {
        "id": 2,
        "name": "Staff",
        "permissions": [
            "subscribers.view",
            "subscribers.create",
            "packages.view"
        ],
        "user_count": 10
    }
}

---

Create Role

Create a new role with specified permissions.

Property	Value
Endpoint	Create Role
Method	POST
URL	/api/v1/roles
Authentication	Bearer Token

Request Body:

{
    "isp_id": 1,
    "branch_id": 1,
    "user_id": 1,
    "name": "New Role",
    "permissions": ["subscribers.view", "packages.view"]
}

Parameter	Type	Required	Description
name	string	Yes	Role name
permissions	array	No	Array of permission keys

Success Response (201 Created):

{
    "success": true,
    "message": "Role created successfully",
    "data": {
        "id": 3
    }
}

---

Update Role

Update role name or permissions.

Property	Value
Endpoint	Update Role
Method	PUT
URL	/api/v1/roles/{id}
Authentication	Bearer Token

Request Body:

{
    "name": "Updated Role",
    "permissions": ["subscribers.view", "subscribers.create"]
}

Success Response (200 OK):

{
    "success": true,
    "message": "Role updated successfully"
}

---

Delete Role

Delete a role from the system.

Property	Value
Endpoint	Delete Role
Method	DELETE
URL	/api/v1/roles/{id}
Authentication	Bearer Token

Success Response (200 OK):

{
    "success": true,
    "message": "Role deleted successfully"
}

Error Response (400 Bad Request):

{
    "success": false,
    "message": "Cannot delete role with assigned users"
}

---

Copy Role

Create a copy of an existing role with a new name.

Property	Value
Endpoint	Copy Role
Method	POST
URL	/api/v1/roles/{id}/copy
Authentication	Bearer Token

Request Body:

{
    "isp_id": 1,
    "branch_id": 1,
    "user_id": 1,
    "name": "Copied Role"
}

Success Response (201 Created):

{
    "success": true,
    "message": "Role copied successfully",
    "data": {
        "id": 4
    }
}