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

# Role Management

> Create and manage roles with custom permissions

## Overview

Roles define what users can do within your workspace. Xenia provides built-in roles and supports custom roles for granular access control.

## Built-in Roles

| Role           | Description             | Permissions                               |
| -------------- | ----------------------- | ----------------------------------------- |
| **Owner**      | Full workspace control  | All permissions, can delete workspace     |
| **Admin**      | Full operational access | All permissions except workspace deletion |
| **Full User**  | Standard access         | Most features, cannot manage users/roles  |
| **Basic User** | Limited access          | View and complete assigned work           |
| **Requester**  | Request-only access     | Can only submit requests                  |

***

## List All Roles

Retrieve all roles available in your workspace.

**Endpoint:** `GET /api/v1/mgt/workspaces/{workspaceId}/roles`

```bash theme={null}
curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/roles" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID"
```

**Response:**

```json theme={null}
{
  "status": true,
  "statusCode": 200,
  "data": [
    {
      "id": "role-uuid-1",
      "title": "Admin",
      "description": "Full access to all features",
      "order": 1,
      "isDefault": true,
      "isCustom": false,
      "permissions": {
        "CAN_MANAGE_USERS": true,
        "CAN_MANAGE_ROLES": true,
        "CAN_MANAGE_TASKS": true,
        "CAN_MANAGE_CHECKLIST": true,
        "CAN_VIEW_REPORTS": true
      }
    },
    {
      "id": "role-uuid-2",
      "title": "Store Manager",
      "description": "Custom role for store managers",
      "order": 10,
      "isDefault": false,
      "isCustom": true,
      "permissions": {
        "CAN_MANAGE_TASKS": true,
        "CAN_VIEW_REPORTS": true,
        "CAN_MANAGE_CHECKLIST": false
      }
    }
  ]
}
```

***

## Get Role by ID

Retrieve details for a specific role.

**Endpoint:** `GET /api/v1/mgt/workspaces/{workspaceId}/roles/{roleId}`

```bash theme={null}
curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/roles/{roleId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID"
```

**Response:**

```json theme={null}
{
  "status": true,
  "statusCode": 200,
  "data": {
    "id": "role-uuid",
    "title": "Store Manager",
    "description": "Custom role for store managers",
    "order": 10,
    "isDefault": false,
    "isCustom": true,
    "permissions": {
      "CAN_MANAGE_TASKS": true,
      "CAN_MANAGE_CHECKLIST": true,
      "CAN_VIEW_REPORTS": true,
      "CAN_MANAGE_USERS": false,
      "CAN_MANAGE_ROLES": false
    },
    "userCount": 15
  }
}
```

***

## List Available Permissions

Get all permissions that can be assigned to roles.

**Endpoint:** `GET /api/v1/mgt/permissions`

```bash theme={null}
curl -X GET "https://api.xenia.team/api/v1/mgt/permissions" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"
```

**Response:**

```json theme={null}
{
  "status": true,
  "statusCode": 200,
  "data": [
    {
      "key": "CAN_MANAGE_USERS",
      "name": "Manage Users",
      "description": "Create, edit, and remove users",
      "category": "User Management"
    },
    {
      "key": "CAN_MANAGE_ROLES",
      "name": "Manage Roles",
      "description": "Create and modify custom roles",
      "category": "User Management"
    },
    {
      "key": "CAN_MANAGE_TASKS",
      "name": "Manage Tasks",
      "description": "Create, assign, and manage tasks",
      "category": "Operations"
    },
    {
      "key": "CAN_MANAGE_CHECKLIST",
      "name": "Manage Templates",
      "description": "Create and edit checklist templates",
      "category": "Operations"
    },
    {
      "key": "CAN_VIEW_REPORTS",
      "name": "View Reports",
      "description": "Access dashboards and reports",
      "category": "Reporting"
    },
    {
      "key": "CAN_MANAGE_LOCATIONS",
      "name": "Manage Locations",
      "description": "Create and edit locations",
      "category": "Organization"
    },
    {
      "key": "CAN_MANAGE_TEAMS",
      "name": "Manage Teams",
      "description": "Create and edit teams",
      "category": "Organization"
    }
  ]
}
```

### Permission Categories

| Category            | Permissions                                                      |
| ------------------- | ---------------------------------------------------------------- |
| **User Management** | `CAN_MANAGE_USERS`, `CAN_MANAGE_ROLES`                           |
| **Operations**      | `CAN_MANAGE_TASKS`, `CAN_MANAGE_CHECKLIST`, `CAN_COMPLETE_TASKS` |
| **Organization**    | `CAN_MANAGE_LOCATIONS`, `CAN_MANAGE_TEAMS`, `CAN_MANAGE_ASSETS`  |
| **Reporting**       | `CAN_VIEW_REPORTS`, `CAN_EXPORT_DATA`                            |

***

## Create Custom Role

Create a new role with specific permissions.

**Endpoint:** `POST /api/v1/mgt/workspaces/{workspaceId}/roles`

```bash theme={null}
curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/roles" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Shift Supervisor",
    "description": "Can manage daily operations but not users",
    "permissions": {
      "CAN_MANAGE_TASKS": true,
      "CAN_MANAGE_CHECKLIST": true,
      "CAN_VIEW_REPORTS": true,
      "CAN_COMPLETE_TASKS": true,
      "CAN_MANAGE_USERS": false,
      "CAN_MANAGE_ROLES": false
    }
  }'
```

**Request Body:**

| Field         | Type   | Required | Description                |
| ------------- | ------ | -------- | -------------------------- |
| `title`       | string | Yes      | Role name (must be unique) |
| `description` | string | No       | Role description           |
| `permissions` | object | Yes      | Permission key-value pairs |

**Response:**

```json theme={null}
{
  "status": true,
  "statusCode": 201,
  "message": "Role created successfully",
  "data": {
    "id": "new-role-uuid",
    "title": "Shift Supervisor",
    "description": "Can manage daily operations but not users",
    "isCustom": true,
    "permissions": {
      "CAN_MANAGE_TASKS": true,
      "CAN_MANAGE_CHECKLIST": true,
      "CAN_VIEW_REPORTS": true,
      "CAN_COMPLETE_TASKS": true
    }
  }
}
```

<Note>
  Custom roles require the **CUSTOM\_ROLES** feature to be enabled for your workspace. Contact your account manager to enable this feature.
</Note>

***

## Update Role

Modify an existing custom role's name, description, or permissions.

**Endpoint:** `PATCH /api/v1/mgt/workspaces/{workspaceId}/roles/{roleId}`

```bash theme={null}
curl -X PATCH "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/roles/{roleId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Senior Shift Supervisor",
    "description": "Updated description with expanded access",
    "permissions": {
      "CAN_MANAGE_TASKS": true,
      "CAN_MANAGE_CHECKLIST": true,
      "CAN_VIEW_REPORTS": true,
      "CAN_COMPLETE_TASKS": true,
      "CAN_EXPORT_DATA": true
    }
  }'
```

**Response:**

```json theme={null}
{
  "status": true,
  "statusCode": 200,
  "message": "Role updated successfully",
  "data": {
    "id": "role-uuid",
    "title": "Senior Shift Supervisor",
    "description": "Updated description with expanded access",
    "permissions": {
      "CAN_MANAGE_TASKS": true,
      "CAN_MANAGE_CHECKLIST": true,
      "CAN_VIEW_REPORTS": true,
      "CAN_COMPLETE_TASKS": true,
      "CAN_EXPORT_DATA": true
    }
  }
}
```

<Warning>
  Changes to role permissions take effect immediately for all users assigned to that role.
</Warning>

***

## Delete Role

Remove a custom role from the workspace.

**Endpoint:** `DELETE /api/v1/mgt/workspaces/{workspaceId}/roles/{roleId}`

```bash theme={null}
curl -X DELETE "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/roles/{roleId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID"
```

**Response:**

```json theme={null}
{
  "status": true,
  "statusCode": 200,
  "message": "Role deleted successfully"
}
```

<Warning>
  You cannot delete a role that has users assigned to it. Reassign users to a different role first.
</Warning>

<Note>
  Built-in roles (Owner, Admin, Full User, Basic User, Requester) cannot be deleted.
</Note>

***

## Assign Users to Role (Bulk)

Assign multiple users to a role at once.

**Endpoint:** `PATCH /api/v1/mgt/workspaces/{workspaceId}/roles/{roleId}/assign-users`

```bash theme={null}
curl -X PATCH "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/roles/{roleId}/assign-users" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "userIds": [
      "user-uuid-1",
      "user-uuid-2",
      "user-uuid-3"
    ]
  }'
```

**Response:**

```json theme={null}
{
  "status": true,
  "statusCode": 200,
  "message": "Users assigned to role successfully",
  "data": {
    "roleId": "role-uuid",
    "assignedCount": 3
  }
}
```

***

## Role Management Workflow Example

### Step 1: List Available Permissions

```bash theme={null}
curl -X GET "https://api.xenia.team/api/v1/mgt/permissions" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"
```

### Step 2: Create a Custom Role

```bash theme={null}
curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/roles" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Regional Manager",
    "description": "Manages multiple locations",
    "permissions": {
      "CAN_MANAGE_TASKS": true,
      "CAN_MANAGE_CHECKLIST": true,
      "CAN_VIEW_REPORTS": true,
      "CAN_MANAGE_LOCATIONS": true
    }
  }'
```

### Step 3: Assign Users to the New Role

```bash theme={null}
curl -X PATCH "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/roles/{roleId}/assign-users" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "userIds": ["user-uuid-1", "user-uuid-2"]
  }'
```

### Step 4: Update Role Permissions (if needed)

```bash theme={null}
curl -X PATCH "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/roles/{roleId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": {
      "CAN_MANAGE_TASKS": true,
      "CAN_MANAGE_CHECKLIST": true,
      "CAN_VIEW_REPORTS": true,
      "CAN_MANAGE_LOCATIONS": true,
      "CAN_EXPORT_DATA": true
    }
  }'
```

***

## Role Design Best Practices

<AccordionGroup>
  <Accordion title="Start with built-in roles">
    Use built-in roles (Admin, Full User, Basic User) for most users. Only create custom roles when you need specific permission combinations.
  </Accordion>

  <Accordion title="Principle of least privilege">
    Assign users the minimum permissions they need to do their job. You can always add permissions later.
  </Accordion>

  <Accordion title="Role naming conventions">
    Use descriptive names that reflect the job function: "Store Manager", "Shift Supervisor", "Safety Inspector" rather than generic names.
  </Accordion>

  <Accordion title="Document your roles">
    Keep track of what each custom role is intended for. Use the description field to document the role's purpose.
  </Accordion>
</AccordionGroup>

***

## Permissions Required

| Action               | Permission Required |
| -------------------- | ------------------- |
| List roles           | Authenticated       |
| Get role details     | Authenticated       |
| List permissions     | Authenticated       |
| Create role          | `CAN_MANAGE_ROLES`  |
| Update role          | `CAN_MANAGE_ROLES`  |
| Delete role          | `CAN_MANAGE_ROLES`  |
| Assign users to role | `CAN_MANAGE_ROLES`  |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="User Lifecycle" icon="user" href="/guides/workflows/user-lifecycle">
    Manage user accounts
  </Card>

  <Card title="Team Management" icon="users" href="/guides/workflows/team-management">
    Organize users into teams
  </Card>
</CardGroup>