Skip to content

Permissions

Kyle Ebbinga edited this page Nov 19, 2026 · 1 revision

Users and permissions

Every command except vx info and vx login needs a login. Permissions are deliberately simple: three fixed levels, granted per project to users or groups, with no custom roles.

The model

  • Levels: each project grants users or groups read (sync, view history), write (submit, lock) or manage (manage access and branches, release anyone's locks). Each level includes the ones below it, and manage applies to that one project only. A user's level is the highest of their own grant and their groups' grants.
  • No default access: a project is visible only to the users and groups granted access to it, and to server admins. To open a project to everyone, grant read to a group everyone is in.
  • Groups make large teams manageable: grant a group once, then add and remove people from it.
  • Server admins manage users and groups and have full access to every project. Server admin is a flag on the user (vx user admin <name>), not a project level, so it can't be granted with vx access. Anyone can create a project and gets manage on it.

User and group names share one namespace, so vx access grant Artists write works without saying which it is.

Common tasks

vx user add alice --display-name "Alice Smith"   # server admin: add a user (prompts for an initial password)
vx group create artists
vx group add artists alice bob
vx access grant artists write                    # in the project's workspace
vx access grant leads manage                     # leads can manage access and branches in this project
vx access                                        # check the result
vx user disable bob                              # someone leaves: blocks logins, ends sessions

See the command reference for every option.

The first admin

On first start, while no users exist, the server creates an admin server admin with the password in VX_ADMIN_PASSWORD. The variable is ignored afterwards. Log in as admin, add real users, make at least one of them a server admin with vx user admin <name>, and change or retire the bootstrap account. See Configuration.

How it works inside

Logins and tokens

vx login posts the username and password to POST /api/v1/auth/login and gets an opaque bearer token starting with vxp_. The server stores only its SHA-256 hash (auth.tokens). The client saves the token in ~/.vertex/credentials, one per server: encrypted with DPAPI on Windows, and readable only by you (mode 600) elsewhere. Every REST and gRPC call sends it. Token lookups go through the cache, so an authenticated call doesn't need a PostgreSQL round trip.

vx logout revokes the token on the server. vx passwd and vx user disable end other sessions.

Brute-force protection

LoginThrottle limits failed logins per username and per client address. The counters live in Redis, so the limit holds across server instances. Behind a reverse proxy, set VX_TRUSTED_PROXIES, or every client shares the proxy's address and one person's typos can lock out the office. vertex_auth_logins_total (by outcome: success, failed, disabled, throttled) shows login activity.

Access checks

Every endpoint requires a logged-in user unless it explicitly opts out ([AllowAnonymous], used by login and server info). Project operations call AccessService.CheckAsync(user, project, level). Access levels are cached; anything that changes grants, group membership or admin flags invalidates the cache. Reads that make a security decision, such as password hashes, are never cached.

Users are never deleted

History refers to users, so they are disabled, never deleted (or anonymized in place for an erasure request). Foreign keys from history to auth.users are ON DELETE RESTRICT.

Clone this wiki locally