---
id: people-and-roles
title: People and roles
sidebar_label: People and roles
---

Two separate things live here: who is in your **account**, and who has access to
each **instance**.

## Account members

**People** lists everyone in the account.

| Role | Can |
| --- | --- |
| `owner` | Everything, including billing |
| `admin` | Invite, create instances, grant instance access |
| `member` | Read |

Owners and admins invite; billing is owner-only.

### Inviting someone

1. **People → Invite**.
2. Enter their email and pick a role.
3. They receive a link and set their own password at `/accept-invite`.

:::info Why you cannot set their password
An invitation creates a person with an **empty password hash**, which cannot
authenticate at all until they set one. If the inviter chose it, that password
would be a shared credential to every instance the person is later granted
access to.

The verification endpoint knows the difference: a token belonging to a
passwordless person reports that a password is needed and is left unspent, so
the link still works when they get to it.
:::

### Removing someone

Removing them from the account removes their portal access. See below for what
happens to their instance access.

## Instance access

Granting access to a **cloud** instance creates a real user inside that
instance's control plane, with `auth_source: "hq"`.

```mermaid
flowchart LR
    P["HQ account member"] -->|grant| U["Control-plane user<br/>auth_source: hq"]
    U --> I["The instance authenticates<br/>this user like any other"]
```

The instance authenticates that user exactly as it authenticates anyone else,
with **no runtime dependency on HQ**. Revoking deletes the row — the control
plane has no disabled state, and a row that exists is a row that can sign in.

### Granting

On an instance record, **Members → Add**, choose an account member and an
instance role (`owner`, `admin`, `member`).

One person holds at most one user per instance, so granting twice is refused
rather than quietly creating a second user.

### Roles inside an instance

Independent of the account role. Someone can be an account `member` and an
instance `owner`, or the reverse.

### Revoking

Removes the user from the instance immediately. Any live session ends with the
session, since the user row backing it is gone.

:::warning Self-hosted instances cannot be granted from HQ
All three member endpoints refuse when the instance is self-hosted. Manage those
users in the instance itself, at **Settings → Access**.
:::

## Passwords

Your HQ password is the single source of truth for every user projected from it.
Changing it in the portal rehashes it and copies the hash to every instance you
have been granted.

Propagation is best-effort and immediate; a background pass compares and repairs
every 15 minutes, so a temporarily unreachable instance catches up on its own.

There is no local password-change endpoint for those users in the control plane,
so there is never a second writer for the hash.

:::warning HQ-managed users are read-only in the instance
Changing the role of, or deleting, an `hq`-sourced user inside the control plane
is refused with `409`. Do it from the portal. The UI shows those rows read-only
with a link back here, but the API is the boundary; the UI is the courtesy.
:::