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

# Client portal permissions

> Which roles can invite portal contacts, share projects and switch the portal on – and why the client role itself holds no permissions at all.

Two capabilities control the client portal: `client.manage` to invite and manage contacts, and `project.manage` to decide which projects each contact can open.

The `client` role that portal contacts hold has **zero** capabilities. It is an empty set, not a small one.

## The capabilities involved

| Capability                 | Label in the permissions list | What it lets you do in the portal                                   |
| -------------------------- | ----------------------------- | ------------------------------------------------------------------- |
| `client.manage`            | **Manage clients**            | See and use the **Portal access** panel, invite contacts, list them |
| `project.manage`           | **Manage projects**           | Tick or untick a project for a contact                              |
| `client.view`              | **View clients**              | Open a client record. Not enough to manage portal access            |
| `member.remove`            | **Remove members**            | Remove a portal contact from the workspace                          |
| `invite.revoke`            | **Revoke pending invites**    | Cancel a portal invite that was not accepted                        |
| `workspace.updateSettings` | **Edit workspace settings**   | Switch the **Client portal** app on or off                          |
| `invoice.manage`           | **Manage invoices**           | Create the invoices a client reads in the portal                    |

## Who holds them by default

| Role                | Invite a contact | Share a project | Remove a contact | Switch the app |
| ------------------- | ---------------- | --------------- | ---------------- | -------------- |
| **Owner**           | Yes              | Yes             | Yes              | Yes            |
| **Admin**           | Yes              | Yes             | Yes              | Yes            |
| **Project Manager** | Yes              | Yes             | No               | No             |
| **Finance**         | No               | No              | No               | No             |
| **Member**          | No               | No              | No               | No             |
| **Contractor**      | No               | No              | No               | No             |
| **Client**          | No               | No              | No               | No             |

Finance holds `client.view` but not `client.manage`, so a Finance user can open a client record without seeing the **Portal access** panel.

<Note>
  The **Portal access** panel is not greyed out for people who cannot use it. It is not rendered at all. If you cannot see it, you do not hold `client.manage`.
</Note>

## Why the client role holds nothing

Most permission systems give an external user a small set of read permissions. TimeTracker does not.

A `client` role has an empty capability set. There is no read permission to grant and no internal screen that a portal contact could be given. What they see comes from a different mechanism entirely – a share between them and a project.

This has three consequences worth knowing:

<Steps>
  <Step title="A client is sent to the portal, always">
    Signing in takes them to `/northwind/portal`. Every internal address refuses them.
  </Step>

  <Step title="A client cannot be promoted by accident">
    The role dropdown on the member record excludes **Client**, and the team invite dialog excludes it too. The only way to create one is a portal invite from a client record.
  </Step>

  <Step title="A client cannot own a workspace">
    The transfer-ownership card says so plainly: `Client contacts can't own a workspace – they only see the portal.`
  </Step>
</Steps>

## The three gates a portal request passes

A portal screen only renders when all three are true.

| Gate      | Question                                             | If it fails                                        |
| --------- | ---------------------------------------------------- | -------------------------------------------------- |
| The app   | Is the **Client portal** app switched on?            | The contact sees **You don't have access to this** |
| The plan  | Does the workspace have the `client_portal` feature? | New invites and new shares are refused             |
| The share | Is this project shared with this contact?            | The contact sees **You don't have access to this** |

<Note>
  The app switch and the plan work differently. Switching the app off blocks contacts from signing in at all. A plan without `client_portal` blocks the **administration** – you cannot invite a new contact or grant a new share – but it does not by itself sign an existing contact out. Switching the app off is what does that.
</Note>

## Sharing versus unsharing

These two are deliberately not symmetric:

| Action            | Needs the app on | Reason                                                  |
| ----------------- | ---------------- | ------------------------------------------------------- |
| Share a project   | Yes              | Granting access to a portal nobody can use is pointless |
| Unshare a project | **No**           | You must always be able to take access away             |

Sharing also refuses a target who is not a `client`-role member of the workspace. You cannot share a project with a colleague this way – project membership is a separate thing.

Every share and unshare is written to your audit history.

## Example

At Northwind Studio:

* **Maya Ellis** (Owner) can do everything – invite Ruth, share projects, remove her, and switch the app off.
* **Tom Whitfield** (Admin) can do the same, except deleting the workspace.
* **Priya Raman** (Project Manager) can invite Ruth and tick or untick her projects, but cannot remove Ruth from the workspace or switch the app off.
* **Daniel Okafor** (Finance) can open the Bluebird Coffee record and issue invoices Ruth will read, but sees no **Portal access** panel.
* **Sarah Lin** (Member) can open client records but cannot touch portal access.
* **Ana Ferreira** (Contractor) cannot see clients at all.

## Capability is not scope

`client.manage` says you **may** manage client portal access. Supervision scope says **which** clients and projects you can reach in the first place.

A Project Manager whose role is scoped to their own projects can only manage portal access for the clients they can already see. Both checks have to pass.

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

## Changing who can manage the portal

You can move these capabilities between roles, or build a custom role that holds exactly what you need.

<Steps>
  <Step title="Open Roles">
    Go to **Settings → Roles**. You need `role.manage`.
  </Step>

  <Step title="Edit or create a role">
    Click a role to edit it, or click **New role**.
  </Step>

  <Step title="Grant the capabilities">
    Under **Clients, projects & tasks**, tick **Manage clients** and **Manage projects**.
  </Step>

  <Step title="Set what the role can see">
    Choose an answer to **What can this role see?** so the role can actually reach the clients it manages.
  </Step>

  <Step title="Save">
    Click **Save changes** or **Create role**.
  </Step>
</Steps>

See [custom roles](/team/custom-roles).

## Common questions

<AccordionGroup>
  <Accordion title="Can I give a client read-only access to a report?">
    No. A portal contact sees the portal and nothing else. Reports are an internal surface.
  </Accordion>

  <Accordion title="Can a Project Manager remove a portal contact?">
    They can revoke an outstanding invite and untick projects, but removing a membership needs `member.remove`, which Project Manager does not hold by default.
  </Accordion>

  <Accordion title="Can I create a custom role for portal management?">
    Yes. Create a role with **Manage clients** and **Manage projects**, and give it a supervision scope that reaches the right clients.
  </Accordion>

  <Accordion title="Can a client be given any capability at all?">
    No capability is offered for a portal contact. Their access comes from project shares, not permissions.
  </Accordion>

  <Accordion title="Why can I see the client but not the Portal access panel?">
    You hold `client.view` but not `client.manage`. Ask an owner or admin.
  </Accordion>
</AccordionGroup>

## Troubleshooting

| Problem                                    | Cause                                              | Fix                                                  |
| ------------------------------------------ | -------------------------------------------------- | ---------------------------------------------------- |
| No **Portal access** panel                 | Missing `client.manage`                            | Ask an owner or admin to grant **Manage clients**    |
| Checkboxes are missing                     | Missing `project.manage`                           | Ask for **Manage projects**                          |
| A share is refused                         | The Client portal app is off, or the plan lacks it | Turn the app on, or upgrade to Pro                   |
| Sharing says the target is not a client    | You are trying to share with a staff member        | Use project membership instead                       |
| A client record is not in your list at all | Your role's supervision scope does not reach it    | See [supervision scope](/concepts/supervision-scope) |

## Related guides

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

  <Card title="Supervision scope" icon="binoculars" href="/concepts/supervision-scope">
    Which people and projects a role reaches.
  </Card>

  <Card title="Custom roles" icon="sliders" href="/team/custom-roles">
    Build a role from the capability list.
  </Card>

  <Card title="Invite a client contact" icon="user-plus" href="/portal/invite-a-client-contact">
    The invite flow.
  </Card>

  <Card title="What clients can see" icon="eye" href="/portal/what-clients-can-see">
    The field-by-field list.
  </Card>

  <Card title="Client permissions" icon="briefcase" href="/clients/client-permissions">
    Managing clients generally.
  </Card>
</CardGroup>