Volume Tokens

A volume token is a UUID that grants a mount client permission to mount a specific volume. Tokens can optionally restrict the mount to a subdirectory within the volume and enforce additional mount flags.

Creating a Volume Token

configure.flexfs create volume-token --volumeID my-volume

This creates a token with full access to the entire volume. The token UUID is auto-generated.

With Mount-Path Scoping

configure.flexfs create volume-token \
  --volumeID my-volume \
  --mountPath /data/project-a

When a mount client uses this token, it sees /data/project-a as the root of the filesystem. Files outside this path are inaccessible.

With Per-Token Flags

configure.flexfs create volume-token \
  --volumeID my-volume \
  --mountPath /data/project-a \
  --flags "ro,noExec" \
  --notes "Read-only access for CI pipeline"

Volume Token Fields

Field	Flag	Type	Default	Description
`volume_id`	`--volumeID`	string	(required)	Volume ID or name
`token`	`--token`	string	(auto-generated)	Access token UUID; auto-generated if omitted
`mount_path`	`--mountPath`	string	(empty)	Subdirectory path to mount as root (e.g., `/data/project`)
`flags`	`--flags`	string	(empty)	Comma-separated mount flags
`notes`	`--notes`	string	(empty)	Free-form notes

Mount-Path Scoping

Mount-path scoping provides subdirectory isolation — each token holder sees only a subtree of the volume as their filesystem root.

For example, given a volume with this structure:

/
├── data/
│   ├── project-a/
│   └── project-b/
└── shared/

You can create separate tokens for each project:

# Token for project A -- sees /data/project-a as /
configure.flexfs create volume-token \
  --volumeID my-volume --mountPath /data/project-a

# Token for project B -- sees /data/project-b as /
configure.flexfs create volume-token \
  --volumeID my-volume --mountPath /data/project-b

Each token holder can only read and write within their scoped path. This is useful for:

Multi-tenant isolation — give each team or customer their own view of the volume
Security boundaries — limit access to sensitive directories
Kubernetes PVs — bind each PersistentVolume to a different subdirectory of the same underlying volume

Per-Token Flags

Flags set on a volume token are additive to the volume-level flags. They can add restrictions but cannot remove restrictions set at the volume level.

For example, if a volume has flags = "acl", a token with flags = "ro" results in the mount having both acl and ro active.

Common per-token flags:

Flag	Description
`ro`	Force read-only mount
`noatime`	Disable access time updates
`acl`	Enable extended ACLs
`xattr`	Enable extended attributes
`noExec`	Prevent binary execution
`noSUID`	Ignore SUID/SGID bits

Listing Volume Tokens

List all tokens:

configure.flexfs list volume-tokens

Filter by volume name:

configure.flexfs list volume-tokens --volumeName my-volume

The list view shows the volume name, token UUID, mount path, flags, notes, and last active timestamp.

Showing Token Details

configure.flexfs show volume-token $TOKEN

The full detail view includes volume_id, token, mount_path, flags, notes, created_at, and active_at (the last time a mount client used this token).

Updating a Token

Update the mount path, flags, or notes on an existing token:

configure.flexfs update volume-token $TOKEN \
  --mountPath /data/project-a/v2 \
  --flags "ro,noExec" \
  --notes "Updated for v2 migration"

Active mounts using this token are not affected until they reconnect.

Deleting a Token

configure.flexfs delete volume-token $TOKEN

Existing mounts using the deleted token will lose access when they next attempt to authenticate with the admin server. This does not forcibly unmount active sessions.

Token Lifecycle

Create a volume token with configure.flexfs create volume-token
Distribute the token UUID to the mount client operator (via the credential file or Kubernetes secret)
Mount — the mount client presents the token to the admin server, which returns volume settings and storage credentials
Active tracking — the active_at timestamp updates each time the token is used
Revoke by deleting the token when access is no longer needed