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