> ## 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.

# Roles and custom permissions

> Build custom roles in workspace settings – choose permissions from the catalog, set what a role can see, and learn which roles are locked.

The **Roles** screen is where you decide what each role in your workspace may do.
You can edit the built-in roles, build custom roles of your own, and control how
far each role can see.

Open it at **Settings → Team Members → Roles**, or go to
`/{workspaceSlug}/settings/roles`.

## Who can open this screen

You need the `role.manage` capability. By default only **Owner** and **Admin**
hold it.

`role.manage` is the permission that governs the permission system itself. It
lets someone hand out permissions they do not hold, so it is never given to a
delivery or finance role by default.

<Note>
  If you do not hold `role.manage`, the **Roles** item does not appear in the
  settings menu. Hiding the link is a convenience, not the security boundary – the
  screen and every save check your permission again on the server.
</Note>

## The roles list

The screen shows one card, **All roles**, with a table of every role in the
workspace.

| Column      | What it shows                                                                                    |
| ----------- | ------------------------------------------------------------------------------------------------ |
| Name        | The role's name. An **Archived** or **In Trash** badge sits next to it when the role is retired. |
| Members     | How many people currently hold this role.                                                        |
| Permissions | How many permissions the role carries.                                                           |
| Type        | **Locked**, **System** or **Custom**.                                                            |

Above the table are a state filter and a **New role** button. Type in the
**Search roles…** box to filter by name, and click a column header to sort by it.

If there is nothing to show, the table reads "No roles yet – create one to get
started."

### The state filter

The dropdown at the top right of the card chooses which roles are listed:
**Active**, **Archived**, **Trash** or **All**. It opens on **Active**.

### System, Custom and Locked

| Type   | Which roles                                         | What you can do                                                                   |
| ------ | --------------------------------------------------- | --------------------------------------------------------------------------------- |
| Locked | Owner and Client                                    | Open the editor to read them. Nothing can be changed, and they cannot be retired. |
| System | Admin, Project Manager, Finance, Member, Contractor | Rename, change permissions, change what they can see, archive or delete.          |
| Custom | Any role you create here                            | Rename, change permissions, change what they can see, archive or delete.          |

<Warning>
  Editing a system role changes it for everyone who already holds it. If you want
  a narrower or wider version of Admin, create a custom role instead of editing the
  real one.
</Warning>

## Create a role

<Steps>
  <Step title="Click New role">
    The role editor opens with an empty name box, focused and ready to type.
  </Step>

  <Step title="Name the role">
    Type a name, for example `Studio Lead`. Names must be filled in, at most 40
    characters, and unique in the workspace.
  </Step>

  <Step title="Choose what the role can see">
    Pick a value in **What can this role see?**. New roles start at the narrowest
    setting.
  </Step>

  <Step title="Tick the permissions">
    Work down the **Permissions** panel and tick what the role may do. Read the
    grey line under each one before you tick it.
  </Step>

  <Step title="Click Create role">
    The role is saved, a "Role created." message appears, and the dialog closes.
    The new role is now available in every role picker – on the roster, on the
    invite dialog and on each person's record.
  </Step>
</Steps>

A new role holds nothing until you tick something. It is a floor, not a copy of
Member.

## The role editor

The same dialog is used for creating and editing, so the layout is identical
both ways.

### The name

The role's name is the heading of the dialog.

* On a **new** role it starts as an input with the placeholder "Name this role".
* On an **existing** role it shows as text with a pencil button beside it. Click
  the pencil to rename.
* Press **Enter** to accept the new name, or **Escape** to put the old one back.
  Escape only cancels the rename – it leaves the dialog open and keeps your
  permission edits.

A **Locked** role shows its name as plain text with no pencil, and the line
underneath reads that this is a built-in role you can see but not change.

### What can this role see?

This select is the role's **supervision scope**. It is not a permission. A
permission says what a role MAY DO. Scope says over WHOM and over WHICH projects.
Both have to pass before anything happens.

| Option                                               | What the role reaches                                                                                                      |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Their projects, and only their own data              | Projects they manage or are assigned to. No one else's time, leave or timecards, even with the permissions ticked below.   |
| Their projects, and people on them                   | Projects they manage or are assigned to, plus anyone who shares one of those projects.                                     |
| Their projects, and people in their group            | Projects they manage or are assigned to, plus anyone in the same group. Being in a group does not by itself add a project. |
| Their projects, and people on them or in their group | Both of the two above.                                                                                                     |
| Everything in the workspace                          | Every project and every person.                                                                                            |

A short hint under the select explains the option you picked.

<Note>
  A role has **one** scope, and it applies to every permission that role holds. If
  a job needs workspace-wide leave but group-only timesheets, that is two roles,
  not one setting.
</Note>

Two roles have a fixed scope you cannot change:

* **Owner** is always "Everything in the workspace". An owner who could be scoped
  down could lock themselves out of their own workspace.
* **Client** is always "Their projects, and only their own data". The client
  portal firewall depends on a portal contact never reaching another person.

For these two the select is disabled and the hint says the role's access is fixed.

### Scope and cross-member permissions must agree

Some permissions act on somebody else's records – approving a timesheet, viewing
another person's time, approving leave, submitting a timecard for someone else,
posting a time adjustment.

If you tick any of those and leave the scope at "only their own data", the save
is blocked and a red line appears under the select. The permission would do
nothing at all otherwise, so the screen refuses the combination instead of
letting you save a role that silently never works.

Fix it by choosing a wider scope, or by clearing the permissions that reach
other people.

### The Permissions panel

The permissions live in a bordered panel with a header that stays put while the
list scrolls.

| Control                 | What it does                                                                                                              |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **X of Y granted**      | A live count of how many permissions this role carries out of the total on offer.                                         |
| **Search permissions…** | Filters the list. It matches the permission's name, its explanation, and its key (typing `time.submitOnBehalf` finds it). |
| Group header            | The section name plus a granted / total count for that section.                                                           |
| **Select all**          | Ticks or unticks every permission currently visible in that group.                                                        |
| Checkbox rows           | One row per permission: a checkbox, its name, and a plain-English line explaining what it lets a person do.               |

Searching narrows what **Select all** acts on. It only ever ticks the rows you
can actually see, so clear the search first if you want a whole group.

If nothing matches, the panel says so and offers to clear the search.

### The permission groups

The catalog is organised into eleven sections, in this order:

<CardGroup cols={2}>
  <Card title="Workspace" icon="building">
    Workspace settings, plan and billing, data export, location rules.
  </Card>

  <Card title="Members & roles" icon="users">
    Invite, add directly, change roles, remove, manage roles, revoke invites, audit log, manage groups.
  </Card>

  <Card title="Clients, projects & tasks" icon="folder">
    View and manage clients, manage projects, tags, and the task actions.
  </Card>

  <Card title="Rates & cost" icon="dollar-sign">
    Manage rates, view billing rates, view cost rates.
  </Card>

  <Card title="Time tracking" icon="clock">
    Track time, edit time entries, view time entry cost.
  </Card>

  <Card title="Timesheets" icon="calendar-days">
    Submit, view and edit others, approve, reopen, adjust, close periods, send reminders.
  </Card>

  <Card title="Timecards" icon="fingerprint">
    Clock in and out, view and submit your own, edit and approve others, reopen.
  </Card>

  <Card title="Schedules" icon="calendar">
    View schedules, manage schedules.
  </Card>

  <Card title="Budgets & money" icon="wallet">
    Project budgets, invoices, payments, expenses and expense categories.
  </Card>

  <Card title="Time off" icon="plane">
    Request leave, approve leave, view others' leave, manage leave policies.
  </Card>

  <Card title="Reports" icon="chart-bar">
    View, create, edit own, manage, share, schedule and export reports.
  </Card>
</CardGroup>

Each permission appears in exactly one group.

<Note>
  Not every permission in the product has a checkbox here yet. Planner and webhook
  permissions are not in the catalog, so a custom role does not carry them. Use a
  built-in role for people who need those.
</Note>

### Deleting the workspace is never a checkbox

`workspace.delete` is reserved to the Owner role. It is not offered as a checkbox
on any editable role, and the server rejects it if it is ever submitted for a
role that is not Owner.

<Warning>
  This closes an escalation path. Without it, an admin could build an "admin-like"
  custom role, grant it workspace deletion, assign it to themselves, and destroy the
  workspace. Only the Owner role can ever hold that permission.
</Warning>

### Saving

**Save changes** (or **Create role** on a new role) stays disabled until the role
has a name and something has actually changed. Name, permissions and scope save
together in one action, so the two never fall out of step.

A refusal from the server appears as a message that names the reason – a pinned
role, a scope clash, or a name already in use.

## Rename a role

<Steps>
  <Step title="Open the role">
    Click the pencil button on the role's row.
  </Step>

  <Step title="Click the pencil beside the name">
    The heading turns into a text box.
  </Step>

  <Step title="Type the new name and save">
    Press **Enter**, then click **Save changes**. A "Role updated." message
    confirms it.
  </Step>
</Steps>

Renaming a role does not change what it may do, and nobody loses access.

## Retire or delete a role

Non-locked roles carry a three-dot menu at the end of the row with **Archive**,
**Restore**, **Delete** and **Delete permanently**, depending on their current
state.

| Action             | What happens                                                                          |
| ------------------ | ------------------------------------------------------------------------------------- |
| Archive            | The role can no longer be assigned. Everyone already holding it keeps it. Reversible. |
| Restore            | The role goes back to Active and can be assigned again.                               |
| Delete             | The role moves to Trash. Reversible from the **Trash** filter.                        |
| Delete permanently | The role is destroyed. People holding it have to be moved first.                      |

Locked roles (Owner and Client) have no lifecycle menu at all.

### Deleting a role that people hold

A role with at least one member gets an extra button on its row, next to the
pencil, that opens the reassign dialog.

<Steps>
  <Step title="Click the reassign button on the role's row">
    A dialog opens headed "Delete role" with the role's name.
  </Step>

  <Step title="Read the count">
    The description tells you how many members will be moved, and that this
    cannot be undone.
  </Step>

  <Step title="Pick a replacement in Move members to">
    The list offers every other role that a person can hold. Owner and Client are
    never options – ownership is handed over on the person's record, and a portal
    contact's role belongs to the client company.
  </Step>

  <Step title="Click Delete role">
    Everyone on the old role moves to the replacement, then the role is deleted.
    A "Role deleted." message confirms it.
  </Step>
</Steps>

**Delete role** stays disabled until you choose a replacement. Nobody is ever
left without a role.

## Only an Owner can hand over ownership

The Owner role is not in any role picker – not on the invite dialog, not on the
add-member form, and not on a person's record.

Only an existing Owner may grant the Owner role, or change or remove an account
that already holds it. An admin who holds `member.changeRole` cannot mint a new
owner and cannot strip the founding owner.

Ownership moves through **Transfer ownership** on the person's record. See
[the member record](/team/member-record).

## Per-person exceptions

Roles are the main tool. There is one exception that is set on the person, not
the role: **clock in and out** can be switched off for a single person under
**Time & attendance** on their record.

It only ever takes a permission away. Nothing set on a person can add a
permission their role does not already grant.

There is also one project-level widening: **Revise task estimates** can be
granted to someone on a single project through their project role, even when
their workspace role does not include it. No other permission works that way.

## Example

Northwind Studio wants a role for studio leads. They run their own projects and
approve the timesheets of the people on them, but they must not see pay costs or
touch billing.

<Steps>
  <Step title="Maya Ellis creates the role">
    Maya (Owner) opens **Settings → Team Members → Roles**, clicks **New role**,
    and names it `Studio Lead`.
  </Step>

  <Step title="She sets what it can see">
    She picks **Their projects, and people on them**. A studio lead reaches the
    people who share a project with them, and nobody else.
  </Step>

  <Step title="She ticks the permissions">
    In **Timesheets** she ticks view others' timesheets and approve or reject
    timesheets. In **Clients, projects & tasks** she ticks manage projects and
    the task permissions.
  </Step>

  <Step title="She leaves cost alone">
    In **Rates & cost** she leaves **View cost rates** unticked, so a studio lead
    never sees what a person costs the business.
  </Step>

  <Step title="She saves and assigns it">
    She clicks **Create role**, then opens Priya Raman's record and switches her
    role to `Studio Lead`.
  </Step>
</Steps>

Priya can now approve Sarah Lin's timesheet on the Bluebird Coffee website
redesign, because Sarah is on that project. She cannot approve Jonas Bergman's
week on Harbor Logistics unless she is on that project too. The permission and
the scope both have to pass.

## Common questions

<AccordionGroup>
  <Accordion title="Can I copy an existing role?">
    No. There is no duplicate action. Create a new role and tick the permissions
    you want. Opening the role you want to copy in a second tab makes this
    quicker.
  </Accordion>

  <Accordion title="Why can't I edit the Owner role?">
    Owner is locked. It holds every permission, including deleting the workspace,
    and its reach is fixed at the whole workspace. Editing it would let someone
    lock the founding owner out of their own workspace.
  </Accordion>

  <Accordion title="Why can't I edit the Client role?">
    Client is locked too. A portal contact holds no internal permissions and
    reaches nobody. That is what keeps client-portal data separated from your
    internal work.
  </Accordion>

  <Accordion title="Why does the save button stay greyed out?">
    Either nothing has changed yet, the role has no name, or you ticked a
    permission that acts on other people while the scope is set to "only their
    own data". A red line under the scope select tells you when it is the last
    one.
  </Accordion>

  <Accordion title="What happens to people on a role I archive?">
    Nothing changes for them. They keep the role and everything it allows. The
    role only stops being offered when someone assigns a role.
  </Accordion>

  <Accordion title="Does a permission I cannot see mean the app is off, or that I am not on the plan?">
    Neither. This screen always shows the whole catalog. An app being off hides
    that area of the product entirely, and a feature not on your plan stays in
    the sidebar behind a paywall. Both are separate from what a role may do.
  </Accordion>
</AccordionGroup>

## Related guides

<CardGroup cols={2}>
  <Card title="Roles and capabilities" icon="key" href="/concepts/roles-and-capabilities">
    The seven roles and the full list of named permissions.
  </Card>

  <Card title="Supervision scope" icon="eye" href="/concepts/supervision-scope">
    How "over whom" works, and why it is separate from a permission.
  </Card>

  <Card title="Custom roles" icon="sliders" href="/team/custom-roles">
    A walkthrough of building a role for a real job.
  </Card>

  <Card title="Per-person permissions" icon="user-cog" href="/team/per-person-permissions">
    The exceptions you set on a person rather than a role.
  </Card>

  <Card title="Change someone's role" icon="repeat" href="/team/change-someones-role">
    Move a person to a different role and what changes for them.
  </Card>

  <Card title="Team members" icon="users" href="/settings/team-members">
    The roster where roles are assigned.
  </Card>
</CardGroup>