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

# Roles & Permissions

> Build custom roles by ticking exactly the permissions each type of staff member needs.

A **role** in Xobito is a named bundle of permissions. Every staff member has one role. There is no built-in hierarchy — two roles can't "inherit" from each other. You build each role independently by ticking the permissions it should include.

<Note>
  The workspace owner (the user with the `is_admin` flag) **bypasses the role system entirely** — they have every permission, always. Roles only matter for other staff.
</Note>

## How roles work

<Steps>
  <Step title="Create a role">
    Name it, tick the permissions, save.
  </Step>

  <Step title="Assign staff to it">
    Open a staff member's profile and pick the role.
  </Step>

  <Step title="Edit it any time">
    Ticking or unticking a permission applies immediately to everyone with that role.
  </Step>
</Steps>

## The default role

Workspaces ship with exactly **one** auto-created role:

| Role      | Permissions             |
| --------- | ----------------------- |
| **Agent** | `tenant.chat.view` only |

That's the minimum — an Agent can open the Live Chat inbox. Anything else needs to be added by ticking more permissions, or by creating additional roles.

<Tip>
  There is no pre-seeded "Admin" role. To give someone admin-like access, create a role and tick every permission. Don't use the `is_admin` flag on regular staff — that flag is reserved for the workspace owner.
</Tip>

## Create a role

Go to **Team → Roles** and click **Create Role**.

<Steps>
  <Step title="Name it">
    For example "Sales Manager" or "Read-only Auditor".
  </Step>

  <Step title="Tick permissions">
    Tick each permission you want this role to have. The full list is below.
  </Step>

  <Step title="Save">
    The role is immediately available when inviting or editing staff.
  </Step>
</Steps>

## Edit or delete a role

* **Edit** — ticking or unticking any permission applies immediately to every staff member with the role.
* **Delete** — only possible if no staff member currently has that role. Reassign those staff first.

<Warning>
  Revoking a permission takes effect on the affected user's next page load. If they're mid-task when you change the role, that specific action may fail partway through. Communicate major changes.
</Warning>

## Super-admin bypass

Xobito has one special behaviour to keep in mind. Any user with the `is_admin` flag on their account (by default, just the workspace owner) passes every permission check, no matter which role they hold.

* You do not need to build an "Everything" role for the workspace owner — they already have access.
* Do not set `is_admin` on regular staff. It's the equivalent of giving them root access.

## Permission reference

There are **77 tenant-scoped permissions** in total, grouped by resource. Tick the ones a role should have.

<Note>
  Permission names use the format `tenant.{resource}.{action}`. All of them apply to the current workspace only — a permission granted here never leaks to any other workspace.
</Note>

### Connect Account (3)

| Permission                          | Allows                                   |
| ----------------------------------- | ---------------------------------------- |
| `tenant.connect_account.view`       | View the WhatsApp connection page        |
| `tenant.connect_account.connect`    | Start the Meta Business connection flow  |
| `tenant.connect_account.disconnect` | Disconnect the WhatsApp Business Account |

### Contacts (6)

| Permission                   | Allows                                  |
| ---------------------------- | --------------------------------------- |
| `tenant.contact.view`        | See every contact in the workspace      |
| `tenant.contact.view_own`    | See only contacts assigned to this user |
| `tenant.contact.create`      | Add new contacts manually               |
| `tenant.contact.edit`        | Edit any contact's fields               |
| `tenant.contact.delete`      | Permanently delete a contact            |
| `tenant.contact.bulk_import` | Import contacts from a CSV              |

### Templates (5)

| Permission                      | Allows                                            |
| ------------------------------- | ------------------------------------------------- |
| `tenant.template.view`          | See the template list                             |
| `tenant.template.load_template` | Load an existing template into the editor for use |
| `tenant.template.create`        | Submit a new template to Meta for approval        |
| `tenant.template.edit`          | Edit a template before submission                 |
| `tenant.template.delete`        | Delete a template from the workspace              |

### Campaigns (6)

| Permission                       | Allows                               |
| -------------------------------- | ------------------------------------ |
| `tenant.campaigns.view`          | See the campaign list                |
| `tenant.campaigns.create`        | Create new campaigns                 |
| `tenant.campaigns.edit`          | Edit an existing campaign            |
| `tenant.campaigns.delete`        | Delete a campaign                    |
| `tenant.campaigns.show_campaign` | See detailed results for a campaign  |
| `tenant.bulk_campaigns.send`     | Trigger the bulk send for a campaign |

### Template Bots (5)

| Permission                   | Allows                         |
| ---------------------------- | ------------------------------ |
| `tenant.template_bot.view`   | See the Template Bot list      |
| `tenant.template_bot.create` | Create new Template Bots       |
| `tenant.template_bot.edit`   | Edit existing Template Bots    |
| `tenant.template_bot.delete` | Delete Template Bots           |
| `tenant.template_bot.clone`  | Clone an existing Template Bot |

### Message Bots (5)

| Permission                  | Allows                        |
| --------------------------- | ----------------------------- |
| `tenant.message_bot.view`   | See the Message Bot list      |
| `tenant.message_bot.create` | Create new Message Bots       |
| `tenant.message_bot.edit`   | Edit existing Message Bots    |
| `tenant.message_bot.delete` | Delete Message Bots           |
| `tenant.message_bot.clone`  | Clone an existing Message Bot |

### Bot Flows (4)

| Permission               | Allows                                         |
| ------------------------ | ---------------------------------------------- |
| `tenant.bot_flow.view`   | See the Bot Flow list and open flows read-only |
| `tenant.bot_flow.create` | Create new flows                               |
| `tenant.bot_flow.edit`   | Edit flows and toggle active state             |
| `tenant.bot_flow.delete` | Delete flows                                   |

### Sources (4)

| Permission             | Allows                        |
| ---------------------- | ----------------------------- |
| `tenant.source.view`   | View the list of lead sources |
| `tenant.source.create` | Create new sources            |
| `tenant.source.edit`   | Edit existing sources         |
| `tenant.source.delete` | Delete sources                |

### Statuses (4)

| Permission             | Allows                         |
| ---------------------- | ------------------------------ |
| `tenant.status.view`   | View the list of lead statuses |
| `tenant.status.create` | Create new statuses            |
| `tenant.status.edit`   | Edit existing statuses         |
| `tenant.status.delete` | Delete statuses                |

### Groups (4)

| Permission            | Allows               |
| --------------------- | -------------------- |
| `tenant.group.view`   | View contact groups  |
| `tenant.group.create` | Create new groups    |
| `tenant.group.edit`   | Edit existing groups |
| `tenant.group.delete` | Delete groups        |

### Custom Fields (4)

| Permission                    | Allows                      |
| ----------------------------- | --------------------------- |
| `tenant.custom_fields.view`   | View the custom field list  |
| `tenant.custom_fields.create` | Create new custom fields    |
| `tenant.custom_fields.edit`   | Edit existing custom fields |
| `tenant.custom_fields.delete` | Delete custom fields        |

### AI Prompts (4)

| Permission                | Allows                   |
| ------------------------- | ------------------------ |
| `tenant.ai_prompt.view`   | See the AI prompt list   |
| `tenant.ai_prompt.create` | Create new AI prompts    |
| `tenant.ai_prompt.edit`   | Edit existing AI prompts |
| `tenant.ai_prompt.delete` | Delete AI prompts        |

### Canned Replies (4)

| Permission                   | Allows                       |
| ---------------------------- | ---------------------------- |
| `tenant.canned_reply.view`   | See the canned reply list    |
| `tenant.canned_reply.create` | Create new canned replies    |
| `tenant.canned_reply.edit`   | Edit existing canned replies |
| `tenant.canned_reply.delete` | Delete canned replies        |

### Chat (3)

| Permission              | Allows                                        |
| ----------------------- | --------------------------------------------- |
| `tenant.chat.view`      | Open the Live Chat inbox                      |
| `tenant.chat.read_only` | Read conversations without being able to send |
| `tenant.chat.delete`    | Delete conversations                          |

### Activity Log (2)

| Permission                   | Allows                     |
| ---------------------------- | -------------------------- |
| `tenant.activity_log.view`   | Read the Activity Log      |
| `tenant.activity_log.delete` | Purge Activity Log entries |

### WhatsApp Settings (2)

| Permission                       | Allows                            |
| -------------------------------- | --------------------------------- |
| `tenant.whatsmark_settings.view` | View WhatsApp-specific settings   |
| `tenant.whatsmark_settings.edit` | Change WhatsApp-specific settings |

### System Settings (2)

| Permission                    | Allows                              |
| ----------------------------- | ----------------------------------- |
| `tenant.system_settings.view` | View workspace-wide system settings |
| `tenant.system_settings.edit` | Edit workspace-wide system settings |

### Staff (4)

| Permission            | Allows                      |
| --------------------- | --------------------------- |
| `tenant.staff.view`   | See the staff list          |
| `tenant.staff.create` | Invite new staff members    |
| `tenant.staff.edit`   | Edit existing staff members |
| `tenant.staff.delete` | Remove staff members        |

### Roles (4)

| Permission           | Allows              |
| -------------------- | ------------------- |
| `tenant.role.view`   | See the role list   |
| `tenant.role.create` | Create new roles    |
| `tenant.role.edit`   | Edit existing roles |
| `tenant.role.delete` | Delete roles        |

### Email Templates (2)

| Permission                   | Allows                                    |
| ---------------------------- | ----------------------------------------- |
| `tenant.email_template.view` | View the list of outgoing email templates |
| `tenant.email_template.edit` | Edit outgoing email templates             |

## Sensible role presets

Xobito doesn't ship any of these — they're just patterns you can build yourself.

<AccordionGroup>
  <Accordion title="Agent (default)">
    Just `tenant.chat.view`. Lets the teammate answer conversations and nothing else.
  </Accordion>

  <Accordion title="Senior agent">
    Agent, plus `tenant.contact.view`, `tenant.contact.edit`, `tenant.canned_reply.view`, `tenant.template.view`. Can look up a contact, use canned replies, and see templates.
  </Accordion>

  <Accordion title="Marketer">
    Contact `view/create/edit/bulk_import`, templates `view/create/edit/load_template`, campaigns `view/create/edit/show_campaign/bulk_campaigns.send`, groups all four, statuses/sources all four, custom fields `view`.
  </Accordion>

  <Accordion title="Manager (near-admin)">
    Everything except: `tenant.staff.delete`, `tenant.role.delete`, `tenant.whatsmark_settings.edit`, `tenant.system_settings.edit`, `tenant.connect_account.disconnect`, `tenant.activity_log.delete`. Keeps the dangerous things for the workspace owner.
  </Accordion>

  <Accordion title="Read-only auditor">
    Every `*.view` permission, plus `tenant.activity_log.view`. Can see everything, can't change anything.
  </Accordion>
</AccordionGroup>

## Permissions that need extra thought

<Warning>
  A handful of permissions are essentially "keys to the kingdom" because they let the holder grant themselves more access. Give them only to your most trusted teammates:

  * `tenant.role.create`, `tenant.role.edit` — can invent a role with any permission set
  * `tenant.staff.create`, `tenant.staff.edit` — can reassign roles for any user
  * `tenant.connect_account.disconnect` — can sever your Meta Business connection
  * `tenant.whatsmark_settings.edit`, `tenant.system_settings.edit` — can change core workspace behaviour
  * `tenant.activity_log.delete` — can erase the audit trail
</Warning>

## What to read next

<CardGroup cols={2}>
  <Card title="Staff Members" icon="user-plus" href="/team/staff-members">
    Invite, edit, and remove staff; assign roles.
  </Card>

  <Card title="Activity Log" icon="clipboard-list" href="/team/activity-log">
    Audit trail of actions taken in your workspace.
  </Card>
</CardGroup>