> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cisisk.projects.bernardopinto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Permissions

> Manage permission levels and assign them to users

Permissions are hierarchical — a user at level N inherits all permissions from levels 0 through N.

* **Level 0**: superadmin (full access)
* **Level 1+**: inherits all lower levels

All endpoints require level 0 permission and a Bearer token.

***

# Permission levels

## List permissions

```
GET /api/v1/permissions
```

```json theme={null}
{
  "success": true,
  "message": "1 permission(s) found",
  "data": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "level": 0,
      "name": "superadmin",
      "description": "Super administrator with all permissions",
      "created_at": "2026-06-28T12:00:00.000Z"
    }
  ],
  "metadata": {}
}
```

***

## Get permission

```
GET /api/v1/permissions/{uuid}
```

```json theme={null}
{
  "success": true,
  "message": "Permission found",
  "data": {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "level": 0,
    "name": "superadmin",
    "description": "Super administrator with all permissions",
    "created_at": "2026-06-28T12:00:00.000Z"
  },
  "metadata": {}
}
```

***

## Create permission

```
POST /api/v1/permissions
```

| Field       | Type    | Required |
| ----------- | ------- | -------- |
| level       | integer | yes      |
| name        | string  | yes      |
| description | string  | no       |

```json theme={null}
{
  "level": 1,
  "name": "admin",
  "description": "Administrator level"
}
```

```json theme={null}
{
  "success": true,
  "message": "Permission created",
  "data": {
    "uuid": "770e8400-e29b-41d4-a716-446655440002",
    "level": 1,
    "name": "admin",
    "description": "Administrator level",
    "created_at": "2026-06-28T12:00:00.000Z"
  },
  "metadata": {}
}
```

***

## Update permission

```
PUT /api/v1/permissions/{uuid}
```

```json theme={null}
{
  "name": "administrator",
  "description": "Updated description"
}
```

```json theme={null}
{
  "success": true,
  "message": "Permission updated",
  "data": {
    "uuid": "770e8400-e29b-41d4-a716-446655440002",
    "level": 1,
    "name": "administrator",
    "description": "Updated description",
    "created_at": "2026-06-28T12:00:00.000Z"
  },
  "metadata": {}
}
```

***

## Delete permission

```
DELETE /api/v1/permissions/{uuid}
```

```json theme={null}
{
  "success": true,
  "message": "Permission deleted",
  "data": null,
  "metadata": {}
}
```

***

# User permission assignments

## Get user's permission

```
GET /api/v1/user-perms/{userUuid}
```

```json theme={null}
{
  "success": true,
  "message": "User permission found",
  "data": {
    "uuid": "880e8400-e29b-41d4-a716-446655440003",
    "user_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "perm_uuid": "00000000-0000-0000-0000-000000000000",
    "level": 0,
    "perm_name": "superadmin",
    "created_at": "2026-06-28T12:00:00.000Z"
  },
  "metadata": {}
}
```

***

## Assign permission

Replace the user's current permission (if any).

```
POST /api/v1/user-perms
```

| Field      | Type   | Required |
| ---------- | ------ | -------- |
| user\_uuid | string | yes      |
| perm\_uuid | string | yes      |

```json theme={null}
{
  "user_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "perm_uuid": "00000000-0000-0000-0000-000000000000"
}
```

```json theme={null}
{
  "success": true,
  "message": "Permission assigned",
  "data": {
    "uuid": "880e8400-e29b-41d4-a716-446655440003",
    "user_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "perm_uuid": "00000000-0000-0000-0000-000000000000",
    "level": 0,
    "perm_name": "superadmin",
    "created_at": "2026-06-28T12:00:00.000Z"
  },
  "metadata": {}
}
```

***

## Remove permission

```
DELETE /api/v1/user-perms/{userUuid}
```

```json theme={null}
{
  "success": true,
  "message": "Permission removed",
  "data": null,
  "metadata": {}
}
```