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

# Members & Roles

> Invite people, manage teams, and understand the role-based access control model.

The Members settings page lets workspace admins control who has access and what they can do. Open it from the sidebar: **Settings → Members**.

You need `members:write` to invite members or change roles, and `members:admin` to remove members. Only **Tenant Admins** can perform these actions by default.

## Member roster

The roster lists every person who has joined or been invited to the workspace, along with their:

* Display name and email
* Role (displayed as the role label)
* Status — `active`, `invited` (pending acceptance), or `suspended`
* Date joined or invitation sent

### Invite a member

<Steps>
  <Step title="Click + Invite member">
    The invite dialog opens.
  </Step>

  <Step title="Enter the email address">
    One email per invite. The address must not already be a member of this workspace.
  </Step>

  <Step title="Choose a role">
    Select from the built-in roles listed below. You cannot grant a role that exceeds your own permission level.
  </Step>

  <Step title="Send the invitation">
    Causeloop sends an email with an acceptance link that expires in 7 days. You can resend it from the member row if needed.
  </Step>
</Steps>

<Note>
  If the recipient's email domain is covered by an active SSO connection, they will be required to sign in via SSO when they accept the invitation.
</Note>

### Change a member's role

Click the role chip in the member row to open the role picker. Select the new role and save. The change takes effect on the member's next authenticated request.

### Remove a member

Click the ellipsis menu on a member row and choose **Remove**. This revokes all active sessions and tokens for that member within this workspace. The workspace must always retain at least one Tenant Admin — removing the last one returns `422 last_admin`.

### Resend an invitation

On an `invited` member row, click **Resend invite**. A fresh invitation email is sent; the original link is not invalidated but the new one replaces it in the UI.

***

## Role catalogue

Causeloop uses a layered inheritance model. Each role inherits the permissions of its parent and adds its own.

| Role key           | Label            | Typical user                                                       |
| ------------------ | ---------------- | ------------------------------------------------------------------ |
| `read_only`        | Read Only        | External stakeholders who only need to view dashboards             |
| `viewer`           | Viewer           | Team members who monitor signals and read reports                  |
| `executive`        | Executive        | Leadership who want dashboards and reports, not operational detail |
| `analyst`          | Analyst          | Engineers or analysts who triage, analyse, and act on patterns     |
| `compliance_admin` | Compliance Admin | Compliance officers who manage data policy and audit trails        |
| `security_admin`   | Security Admin   | Security engineers who manage SSO, API tokens, and audit logs      |
| `manager`          | Manager          | Team leads who also manage members and reports                     |
| `tenant_admin`     | Workspace Admin  | Full administrative access to the workspace                        |

<Note>
  The API also exposes a legacy `role` field that maps these keys to `admin`, `analyst`, or `viewer` for backwards compatibility. The `role_key` field on membership objects carries the precise role key shown above.
</Note>

### Inheritance graph

```
read_only
  └── viewer
        ├── executive          (narrows: removes members:read, connectors:read)
        ├── compliance_admin   (adds: data policy write, audit:read, reports write/delete)
        └── analyst            (adds: write access to issues, patterns, predictions,
              │                        recommendations, webhooks, connectors)
              ├── manager      (adds: members:read, reports delete, recommendations:admin)
              │     └── tenant_admin   (adds: workspace:*, inherits everything)
              └── security_admin       (adds: workspace.security:rw, api_tokens:*, audit:read)
```

***

## Permissions matrix

The table below shows which actions each built-in role can perform on the Settings screens. TA = Tenant Admin, SEC = Security Admin, CMP = Compliance Admin, MGR = Manager, ANL = Analyst, EXE = Executive, VWR = Viewer, RO = Read Only.

### Settings — Members

| Action                    | Required permission            | TA | SEC | CMP | MGR | ANL | EXE | VWR | RO |
| ------------------------- | ------------------------------ | -- | --- | --- | --- | --- | --- | --- | -- |
| View member roster        | `members:read`                 | ✓  | ✓   | ✓   | ✓   | ✓   | —   | ✓   | —  |
| Invite member             | `members:write`                | ✓  | —   | —   | —   | —   | —   | —   | —  |
| Change role               | `members:write`                | ✓  | —   | —   | —   | —   | —   | —   | —  |
| Assign custom/multi roles | `members:write` + `roles:read` | ✓  | —   | —   | —   | —   | —   | —   | —  |
| Remove member             | `members:admin`                | ✓  | —   | —   | —   | —   | —   | —   | —  |
| Resend invite             | `members:write`                | ✓  | —   | —   | —   | —   | —   | —   | —  |
| Configure SSO             | `workspace.security:write`     | ✓  | ✓   | —   | —   | —   | —   | —   | —  |

<Note>
  A Tenant Admin cannot demote themselves if they are the last admin in the workspace (`403 cannot_change_self`). Privilege escalation — granting a role that exceeds the actor's own grants — is blocked with `403 privilege_escalation`.
</Note>

***

## Teams

Teams are sub-groups within a workspace. They let you assign patterns, recommendations, and alert rules to a named group rather than individual members.

### Create a team

<Steps>
  <Step title="Click Teams → New team">
    Enter a name and optional description.
  </Step>

  <Step title="Add members">
    Search for existing workspace members to add. You can add or remove members at any time.
  </Step>

  <Step title="Save">
    The team is created. You can now assign it as the owner of patterns, recommendations, and alert rules.
  </Step>
</Steps>

### Manage team members

Open the team detail view and use the **+ Add member** button to include members, or click the remove icon next to a member to take them out of the team. Removing a member from a team does not remove them from the workspace.

***

## API endpoints

| Method   | Path                             | Description                 |
| -------- | -------------------------------- | --------------------------- |
| `GET`    | `/v1/members`                    | List all workspace members  |
| `POST`   | `/v1/members`                    | Invite a new member         |
| `PATCH`  | `/v1/members/{id}`               | Update a member's role      |
| `DELETE` | `/v1/members/{id}`               | Remove a member             |
| `POST`   | `/v1/members/{id}/resend-invite` | Resend the invitation email |
| `GET`    | `/v1/teams`                      | List teams                  |
| `POST`   | `/v1/teams`                      | Create a team               |
| `POST`   | `/v1/teams/{id}/members`         | Add a member to a team      |
| `DELETE` | `/v1/teams/{id}/members/{uid}`   | Remove a member from a team |

For the full REST specification see [API Reference](/api-reference/overview).