Role Management

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

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:

{
  "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}

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:

{
  "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

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:

{
  "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

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:

{
  "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
    }
  }
}

Custom roles require the CUSTOM_ROLES feature to be enabled for your workspace. Contact your account manager to enable this feature.

Update Role

Modify an existing custom role’s name, description, or permissions. Endpoint: PATCH /api/v1/mgt/workspaces/{workspaceId}/roles/{roleId}

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:

{
  "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
    }
  }
}

Changes to role permissions take effect immediately for all users assigned to that role.

Delete Role

Remove a custom role from the workspace. Endpoint: DELETE /api/v1/mgt/workspaces/{workspaceId}/roles/{roleId}

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:

{
  "status": true,
  "statusCode": 200,
  "message": "Role deleted successfully"
}

You cannot delete a role that has users assigned to it. Reassign users to a different role first.

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

Assign Users to Role (Bulk)

Assign multiple users to a role at once. Endpoint: PATCH /api/v1/mgt/workspaces/{workspaceId}/roles/{roleId}/assign-users

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:

{
  "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

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

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

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)

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

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.

Principle of least privilege

Assign users the minimum permissions they need to do their job. You can always add permissions later.

Role naming conventions

Use descriptive names that reflect the job function: “Store Manager”, “Shift Supervisor”, “Safety Inspector” rather than generic names.

Document your roles

Keep track of what each custom role is intended for. Use the description field to document the role’s purpose.

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`

Getting Started

Workflows

Integrations

Overview

Built-in Roles

List All Roles

Get Role by ID

List Available Permissions

Permission Categories

Create Custom Role

Update Role

Delete Role

Assign Users to Role (Bulk)

Role Management Workflow Example

Step 1: List Available Permissions

Step 2: Create a Custom Role

Step 3: Assign Users to the New Role

Step 4: Update Role Permissions (if needed)

Role Design Best Practices

Permissions Required

Next Steps

User Lifecycle

Team Management

Getting Started

Workflows

Integrations

​Overview

​Built-in Roles

​List All Roles

​Get Role by ID

​List Available Permissions

​Permission Categories

​Create Custom Role

​Update Role

​Delete Role

​Assign Users to Role (Bulk)

​Role Management Workflow Example

​Step 1: List Available Permissions

​Step 2: Create a Custom Role

​Step 3: Assign Users to the New Role

​Step 4: Update Role Permissions (if needed)

​Role Design Best Practices

​Permissions Required

​Next Steps

User Lifecycle

Team Management

Overview

Built-in Roles

List All Roles

Get Role by ID

List Available Permissions

Permission Categories

Create Custom Role

Update Role

Delete Role

Assign Users to Role (Bulk)

Role Management Workflow Example

Step 1: List Available Permissions

Step 2: Create a Custom Role

Step 3: Assign Users to the New Role

Step 4: Update Role Permissions (if needed)

Role Design Best Practices

Permissions Required

Next Steps