vantage-docs/docs/hq/people-and-roles.md

id, title, sidebar_label

id	title	sidebar_label
people-and-roles	People and roles	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".

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