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

# Custom roles

> Build your own roles in TimeTracker from the permission list, set what each role can see, and learn which actions only the owner can ever hold.

If none of the built-in roles fits, build your own. **Settings → Roles** lets you create a role, tick exactly the permissions it needs, and decide whose data it can reach.

You need the `role.manage` capability.

## When to create a custom role

<CardGroup cols={2}>
  <Card title="Good reasons" icon="check">
    A bookkeeper who records payments but never sees cost rates. A team lead who approves timesheets for one group. An auditor who reads reports and nothing else.
  </Card>

  <Card title="Not a reason" icon="x">
    One person needs one thing switched off. Use a per-person exception, or accept the nearest role – see <a href="/team/per-person-permissions">per-person permissions</a>.
  </Card>
</CardGroup>

## The Roles page

Go to **Settings → Roles**. The page is described as `What each role can do in this workspace.`

One card, **All roles**, described as `System roles are fixed; create custom roles for anything in between.` A **New role** button sits in its header.

| Column          | What it shows                                  |
| --------------- | ---------------------------------------------- |
| **Name**        | The role name                                  |
| **Members**     | How many people hold it                        |
| **Permissions** | A count, such as `43 permissions`              |
| **Type**        | A badge – **Locked**, **System** or **Custom** |
|                 | An unlabelled actions column                   |

A search box with the placeholder `Search roles…` sits above the table. Empty state: `No roles yet – create one to get started.`

Row actions are a pencil to edit (or view, when locked), a reassign icon when the role has members, and the archive and delete menu on roles that are not locked.

## Which roles you can edit

| Role                | Type badge | Rename | Edit permissions | Delete |
| ------------------- | ---------- | ------ | ---------------- | ------ |
| **Owner**           | Locked     | Yes    | **No**           | **No** |
| **Client**          | Locked     | Yes    | **No**           | **No** |
| **Admin**           | System     | Yes    | Yes              | Yes    |
| **Project Manager** | System     | Yes    | Yes              | Yes    |
| **Finance**         | System     | Yes    | Yes              | Yes    |
| **Member**          | System     | Yes    | Yes              | Yes    |
| **Contractor**      | System     | Yes    | Yes              | Yes    |
| Anything you create | Custom     | Yes    | Yes              | Yes    |

<Warning>
  **Owner** and **Client** are locked. Their permissions cannot be edited and they cannot be deleted. Opening one shows a read-only view: `This is a built-in role. You can see what it does, but not change it.`

  The Owner role must always hold everything, and the Client role must always hold nothing. Those two invariants are what keep the whole permission model honest.
</Warning>

## Create a role

<Steps>
  <Step title="Open Roles">
    Go to **Settings → Roles**.
  </Step>

  <Step title="Click New role">
    The dialog opens. Its description reads `Choose what this role can see, and what it can do.`
  </Step>

  <Step title="Name it">
    The role name **is** the dialog title. Type over the placeholder `Name this role`. Press Enter to commit. Names are up to 40 characters.
  </Step>

  <Step title="Set what it can see">
    Choose an answer to **What can this role see?** This is the role's supervision scope.
  </Step>

  <Step title="Tick the permissions">
    Work down the grouped list, or use the search box.
  </Step>

  <Step title="Create it">
    Click **Create role**. A toast confirms `Role created.`
  </Step>
</Steps>

<Note>
  There is no description field, and no "copy from" or "duplicate" control. Start from an empty role and tick what you need.
</Note>

## The permission list

The permission matrix is headed **Permissions** with a live counter, `12 of 62 granted`.

| Control                  | What it does                                                                          |
| ------------------------ | ------------------------------------------------------------------------------------- |
| Search box               | Placeholder `Search permissions…`. Matches the label, the hint, or the permission key |
| **Select all** per group | Ticks a whole group, showing `4/8` as you go                                          |
| Each row                 | A checkbox, a bold label and a grey explanation                                       |

Group headings stay pinned as you scroll. The eleven groups are:

| Group                         | What it covers                                       |
| ----------------------------- | ---------------------------------------------------- |
| **Workspace**                 | Settings, plan and billing, exports, location rules  |
| **Members & roles**           | Invites, adding people, roles, groups, audit log     |
| **Clients, projects & tasks** | Clients, projects, tags and task actions             |
| **Rates & cost**              | Setting and seeing billing and cost rates            |
| **Time tracking**             | Tracking and editing your own time                   |
| **Timesheets**                | Submitting, approving, adjusting and closing periods |
| **Timecards**                 | Clocking in and out, and timecard approvals          |
| **Schedules**                 | Viewing and managing working patterns                |
| **Budgets & money**           | Budgets, invoices, payments and expenses             |
| **Time off**                  | Requesting, approving and setting policies           |
| **Reports**                   | Viewing, building, sharing, scheduling and exporting |

If a search matches nothing you see `No permissions match "x". Try a different word, or clear the search to see all 62.`

## What can never be granted

<Warning>
  **Deleting the workspace is owner-exclusive.** It is not offered as a checkbox on any other role, and the server refuses it if it is attempted: `"workspace.delete" belongs to the owner role and can't be granted to another role.`

  This closes the obvious escalation path – an admin cannot mint an "admin-plus" role that can delete the whole workspace.
</Warning>

Two more powers are keyed to the Owner role itself rather than to a permission, so a custom role cannot pick them up:

| Owner-only power       | Why it is not a checkbox                                 |
| ---------------------- | -------------------------------------------------------- |
| Deleting the workspace | Irreversible – it destroys the tenant                    |
| Granting ownership     | Ownership moves only by transfer, from the current owner |

Everything else in the list can be given to a custom role.

## What can this role see?

Permissions say **may you**. Scope says **for whom**. Both must pass.

| Option                                                 | Reach                                 |
| ------------------------------------------------------ | ------------------------------------- |
| `Their projects, and only their own data`              | Just themselves                       |
| `Their projects, and people on them`                   | Everyone on their projects            |
| `Their projects, and people in their group`            | Everyone who shares a group with them |
| `Their projects, and people on them or in their group` | Both of the above                     |
| `Everything in the workspace`                          | The whole roster                      |

<Warning>
  A role that can act on other people needs someone to act on. If you tick a cross-member permission and leave the scope at "only their own data", saving is blocked:

  `This role can act on other people, so it needs someone to act on. Pick whose data it covers, or turn off that permission below.`
</Warning>

Scope is set once per role, not per permission. A role that needs workspace-wide leave visibility but group-scoped timesheets is two roles, not one.

See [supervision scope](/concepts/supervision-scope).

## Edit a role

Click the pencil on the row. The same dialog opens with **Save changes** instead of **Create role**. A toast confirms `Role updated.`

People holding the role pick up the change immediately.

## Delete a role

What happens depends on whether anyone holds it.

### Nobody holds it

Use the archive and delete menu on the row, the same as anywhere else in TimeTracker.

### People hold it

You must say where they go.

<Steps>
  <Step title="Click the reassign icon">
    Its label reads `Reassign members of {name} and delete it`.
  </Step>

  <Step title="Read the warning">
    The dialog is titled **Delete role "{name}"?** with the text `Its 3 member(s) will be moved to the role you select. This can't be undone.`
  </Step>

  <Step title="Pick a replacement">
    The **Move members to** dropdown lists every role except this one and the locked ones. Its placeholder is `Choose a role`.
  </Step>

  <Step title="Delete">
    Click **Delete role**. The button stays disabled until you pick a replacement. A toast confirms `Role deleted.`
  </Step>
</Steps>

Everyone is moved first, then the role is removed – both in one step, so nobody is ever left without a role. Each move is written to your audit history.

You cannot move people to Owner or Client this way.

## Using a custom role

A custom role behaves exactly like a built-in one.

| Where                                    | Available |
| ---------------------------------------- | --------- |
| The **Invite teammate** role dropdown    | Yes       |
| The **Add member** role dropdown         | Yes       |
| The **Role** dropdown on a member record | Yes       |
| **Change role** on a pending invite      | Yes       |

## Example

Northwind Studio hires a part-time bookkeeper. Finance is too broad – it can see the audit log and export the whole workspace.

Maya creates a role called **Bookkeeper**:

<Steps>
  <Step title="Scope">
    **What can this role see?** is set to `Everything in the workspace`, because invoices span every client.
  </Step>

  <Step title="Permissions ticked">
    **Manage invoices**, **Record payments**, **Approve or reject expenses**, **Manage expense categories**, **View billing rates**, **View reports**.
  </Step>

  <Step title="Permissions left off">
    **View cost rates**, **Export workspace data**, **Read the audit log**, and everything under Members & roles.
  </Step>

  <Step title="Result">
    The counter reads `6 of 62 granted`. The bookkeeper can bill clients and chase payments, but never sees what anyone costs Northwind, and cannot export the workspace.
  </Step>
</Steps>

## Permissions

| Action                                | Capability          | Roles that hold it by default |
| ------------------------------------- | ------------------- | ----------------------------- |
| Open the Roles page                   | `role.manage`       | Owner, Admin                  |
| Create, edit, rename or delete a role | `role.manage`       | Owner, Admin                  |
| Assign a role to a person             | `member.changeRole` | Owner, Admin                  |

The permission list describes `role.manage` as **Manage roles & permissions**: `Create roles, rename them, delete them, and choose what each one can do. This includes handing out permissions they do not have themselves.`

<Warning>
  `role.manage` is powerful. Someone with it can create a role holding permissions they do not have themselves, then assign it. Give it only to people you trust with the whole workspace.
</Warning>

## Common questions

<AccordionGroup>
  <Accordion title="Can I edit the built-in Admin or Member role?">
    Yes. Only **Owner** and **Client** are locked. The other five built-in roles can be renamed, edited and deleted.
  </Accordion>

  <Accordion title="Can I create a role that deletes the workspace?">
    No. That one action is reserved to the Owner and is not offered as a checkbox anywhere.
  </Accordion>

  <Accordion title="What happens to people when I delete their role?">
    You pick a replacement role, everyone is moved to it, and then the role is removed – all in one step.
  </Accordion>

  <Accordion title="Can I copy an existing role as a starting point?">
    There is no duplicate control. Open the role you want to copy, note its ticks, then create a new one.
  </Accordion>

  <Accordion title="Why are there 62 permissions and not 66?">
    Four are not offered as checkboxes – deleting the workspace, which is owner-only, and three that are not managed through the role editor.
  </Accordion>

  <Accordion title="Can I set scope per permission?">
    No. Scope is one setting for the whole role. Split it into two roles if you need two different reaches.
  </Accordion>
</AccordionGroup>

## Troubleshooting

| Problem                       | Message                                                                                           | Fix                                       |
| ----------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| No **Roles** item in settings | –                                                                                                 | You do not hold `role.manage`             |
| Empty name                    | `Give this role a name.`                                                                          | Type a name                               |
| Name too long                 | `That role name is too long. Use 40 characters or fewer.`                                         | Use 40 characters or fewer                |
| Duplicate name                | `A role called "X" already exists. Pick a different name.`                                        | Choose another                            |
| Owner-only permission         | `"workspace.delete" belongs to the owner role and can't be granted to another role.`              | It cannot be granted                      |
| Locked role                   | `A built-in role's permissions can't be edited. Duplicate it into a custom role and change that.` | Create a custom role instead              |
| Deleting a held role          | `This role still has people in it. Choose which role they should move to before deleting it.`     | Pick a replacement                        |
| Same replacement              | `Pick a different role for these people to move to.`                                              | Choose a different role                   |
| Scope conflict                | `This role can act on other people, so it needs someone to act on. …`                             | Widen the scope, or untick the permission |

## Related guides

<CardGroup cols={2}>
  <Card title="Roles and capabilities" icon="shield" href="/concepts/roles-and-capabilities">
    The permission model.
  </Card>

  <Card title="Supervision scope" icon="binoculars" href="/concepts/supervision-scope">
    Deciding whose data a role reaches.
  </Card>

  <Card title="Capabilities reference" icon="list" href="/reference/capabilities">
    Every permission, one by one.
  </Card>

  <Card title="Change someone's role" icon="user-cog" href="/team/change-someones-role">
    Assign the role you built.
  </Card>

  <Card title="Per-person permissions" icon="sliders" href="/team/per-person-permissions">
    Exceptions for one person.
  </Card>

  <Card title="Groups" icon="users" href="/team/groups">
    How group scope resolves.
  </Card>
</CardGroup>