Reference
Permissions
Access in Vektor is an access control list: every grant pairs a user or a group with a role on a specific resource. Three roles, a handful of feature flags, and per-document scoping cover everything from a private draft to a fully public space.
Browse documentation
Getting started
Operations
Changelog
Every space keeps its own access control list. An entry names a grantee (a user, or a group), a resource (the space, a document, a document tree, a category, an extension, or a secret), and a role. Nothing is implicit: a user who holds no entry, directly or through a group, cannot see the space at all.
Roles
There are three roles, and they are strictly ordered: viewer < editor < owner. A check for “at least editor” is satisfied by an owner, and every role includes the ones below it.
| Role | Grants |
|---|---|
viewer | Read access. Can open documents, search, and browse the database views they can see. No writes, no commenting by default. |
editor | Everything a viewer can do, plus creating and editing documents, uploading files, reading secrets, and inviting people as viewer or editor. |
owner | Full control: space settings, membership (including granting and revoking owner), feature overrides, secrets, and access tokens. |
The user who creates a space becomes its owner. The user who creates a document becomes owner of that document, independent of their space role.
Feature permissions
Some capabilities are not a matter of read versus write, so they are modelled separately as features. Each feature has a default per role, and an owner can override it for a single user or a whole group, granting it or explicitly denying it.
| Feature | Viewer | Editor | Owner | Description |
|---|---|---|---|---|
comment | — | yes | yes | Write comments and reply in threads. |
view_history | — | yes | yes | See document revisions and diffs. |
view_audit | — | yes | yes | Read the audit log / activity feed. |
manage_extensions | — | — | yes | Install, update, and remove extensions. |
An explicit entry always wins over the default: denying view_history to an editor takes it away, and granting comment to a group of viewers lets them comment without giving them write access. Removing the override restores the role default. A user-specific override takes precedence over a group override.
Where a grant applies
Grants are not limited to the space as a whole. The resource types are:
| Resource type | Covers |
|---|---|
space | The whole space. This is the “membership” role shown in space settings. |
document | A single document. |
document_tree | A document and everything nested under it. |
category | Every document assigned to a category (and their child pages). |
extension | A single installed extension. Falls back to the space role when no entry exists. |
secret | A stored space secret. |
feature | A feature permission (see below) rather than a resource. |
How access is resolved
When a request touches a document, Vektor collects every grant that could apply to it:
- a grant on the document itself,
- a
document_treegrant on the document or on any of its ancestors, - a
categorygrant on any category the document (or an ancestor) belongs to.
The highest of those decides the outcome. Only if none of them exists does the space-level role apply. That has one consequence worth internalising: a document-scoped grant replaces the space role for that document rather than adding to it, so giving a space editor an explicit viewer grant on one document makes that document read-only for them.
Direct user grants and group grants are pooled the same way, with the highest applicable role winning, so group membership can only ever widen access, never narrow it.
Groups
A grant can target a group name instead of a user, which is how you keep access in sync with your identity provider. Group membership comes from the wiki_groups claim of the OAuth profile and is stored on the user record at login. Names must match ^[A-Za-z0-9_.:-]{1,64}$; malformed entries are dropped, and at most 100 groups are kept per user.
Set OAUTH_ALLOWED_GROUPS to a comma-separated allowlist to restrict which claims your IdP is permitted to assign. Any group outside the list is discarded at login.
The public group
Every request belongs to the implicit public group, including unauthenticated ones. Granting public a role is therefore how you publish something: viewer on the space makes the space readable without signing in, and a public grant on a single document or tree publishes just that part.
Managing access
Space membership
Open space settings → General, where the Members section lists everyone with a space-level role along with any groups that were granted access. Invite people by email address, change a role in place, or remove a member. You cannot change or remove someone whose role is above your own, and space settings themselves are owner-only.
Sharing a single document
The Share dialog on a document has three tabs, matching the scopes above:
- This document: invite someone as viewer or editor. Tick Include child pages to make it a document-tree grant instead.
- Category: grant a role on every document in a category.
- Entire space: the same list as space settings, including
owner.
Who can change what
| Operation | Minimum role |
|---|---|
| List permissions of a space or resource | editor |
| See your own role and feature permissions | any access |
| List space members | viewer |
| See member email addresses | editor |
| Grant viewer or editor (space, document, document tree, category) | editor |
| Grant owner | owner |
| Revoke a document- or tree-scoped grant | editor |
| Revoke a space-level role | owner |
| Grant, deny, or reset a feature permission | owner |
| Create or revoke access tokens | owner |
| Open space settings, read the audit log config, manage secrets (writes) | owner |
Access tokens
An access token is a delegation of access, not an identity: it holds its own ACL entries and is bound to one resource and role. Only an owner can create one, in space settings → Access Tokens, and a token can never carry more than its creator holds on that resource. Tokens may be given an expiry (expiresInDays) and can be revoked or deleted at any time.
The special extensions permission is a space-wide capability rather than a resource grant: it gives the token manage_extensions, which is what vektor extension upload and the MCP install_extension tool need. See the extensions guide.
Auditing changes
Every grant and revoke is written to the audit log as an acl_grant or acl_revoke event, recording who made the change, who it affected, the new role, and the previous value. Document- and tree-scoped changes are logged against the document, so they appear in that document's activity feed; everything else is logged against the space. Reading the log requires the view_audit feature.