Repository navigation
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.
-
Levels: each project grants users or groups
read(sync, view history),write(submit, lock) ormanage(manage access and branches, release anyone's locks). Each level includes the ones below it, andmanageapplies 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
readto 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 withvx access. Anyone can create a project and getsmanageon it.
User and group names share one namespace, so vx access grant Artists write works without saying which it is.
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 sessionsSee the command reference for every option.
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.
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.
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.
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.
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.