Vantage/vantage-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Self review of doc pages

Browse Source
This commit is contained in:
mrhid6
2026-08-10 16:32:23 +01:00
parent bd7b3256fc
commit 83c38db92e
34 changed files with 860 additions and 991 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/hq/people-and-roles.md
+24 -31
View File
@@ -26,14 +26,11 @@ Owners and admins invite; billing is owner-only.
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.
An invited person cannot sign in at all until they set their own password. If
you chose it for them, it would be a shared password to every instance they are
later given 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.
Their invitation link stays valid until they use it to set that password.
:::
### Removing someone
@@ -43,26 +40,26 @@ 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"`.
Granting access to a **cloud** instance creates a real account inside that
instance, marked as managed by Vantage 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"]
P["Person in your Vantage HQ account"] -->|you grant access| U["Account inside the instance"]
U --> I["They sign in at the instance,<br/>like anyone else"]
```
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.
They then sign in at the instance itself, and that keeps working whether or not
Vantage HQ is reachable. Revoking removes the account outright, so access ends
immediately.
### 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.
One person gets one account per instance, so granting twice is refused rather
than quietly creating a second.
### Roles inside an instance
@@ -71,28 +68,24 @@ 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.
Removes their access immediately, and ends any session they have open.
:::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**.
Vantage HQ cannot add or remove people in a self-hosted install. Manage them in
the install 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.
One Vantage HQ password covers you and every cloud instance you have been given
access to. Change it in the portal and it changes everywhere, within about 15
minutes at worst if an instance is briefly unreachable.
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.
Those people cannot change that password inside an instance, so there is only
ever one place it is set.
:::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.
Changing the role of, or removing, someone managed by Vantage HQ has to be done
from the portal. Inside the instance those rows are read-only, with a link back
here.
:::