Manage File System Tokens
In TiDB Cloud Filesystem, you can use file system tokens to give users, applications, and automation access to a file system without sharing your TiDB Cloud API credentials.
An owner token grants full access to a file system. A scoped token limits access to specific paths and operations. For details, see Authorization.
Prerequisites
Before you begin:
- Install TiDB Cloud CLI.
- Have access to an existing file system in TiDB Cloud Filesystem. If you do not have one, follow Get Started with TiDB Cloud Filesystem to create one.
Listing, enabling, disabling, and deleting tokens require either an owner token supplied through TI_FS_TOKEN or --fs-token, or TiDB Cloud API credentials with an explicit --file-system-id. These operations do not use a locally stored token automatically. Scoped-token generation can use a locally stored owner token. Each section below explains any additional requirements.
Import an existing token
If you already have a file system token, import it to the local CLI credential store:
ti fs import-file-system-token --from-file ./fs-token --region aws-us-east-1
The CLI validates the token, extracts the file system ID from it, verifies connectivity, and stores the token locally.
Generate an owner token
Creating a file system returns an owner token. That token does not expire, and the CLI stores it locally and uses it for later commands. Before you revoke it, generate and validate a replacement as described in Rotate or revoke a token. Tokens you generate later with --ttl expire on their own.
Generate an additional owner token when another trusted environment needs full access.
To generate an additional owner token, configure TiDB Cloud API credentials and obtain the file system ID.
Generate the token and save its one-time plaintext response securely:
umask 077
ti fs generate-file-system-token \
--file-system-id "<file-system-id>" \
--token-name ci \
--ttl 24h \
--query fs_token \
--output text > ./ci-token
--query fs_token --output text writes the token value on its own, which is the format that import-file-system-token --from-file expects. Without those options the command writes its full JSON response, and importing that file fails with invalid FS token format. The token ID that you need in order to revoke the token later is available at any time from ti fs list-file-system-tokens.
The CLI does not store the generated token locally by default. To store it locally, add --store-locally to the preceding command. If a different token is already stored for this file system, also add --replace.
Generate and delegate a scoped token
On a trusted machine, use an owner token to generate a scoped token. Supply the owner token through --fs-token or TI_FS_TOKEN, or use the owner token stored locally for the selected file system.
Before using this example, create the remote /workspace directory if it does not exist. Use the locally stored owner token to grant an agent permission to read, list, and write files in that directory:
SCOPED_TOKEN="$(ti fs generate-file-system-scoped-token \
--file-system-id "<file-system-id>" \
--subject report-agent \
--ttl 24h \
--allow /workspace:read,list,write \
--query fs_token --output text)"
Transfer the token through a secret manager. In the receiving environment, provide the scoped token and the file system region:
export TI_FS_TOKEN="<scoped-token>"
export TI_REGION_CODE="<filesystem-region-code>"
ti fs list-files --path /workspace
The --allow value uses the format <path>:<comma-separated-operations>. Supported operations are read, list, search, write, and delete; search requires read. In this example, the token permits read, list, and write operations under /workspace.
To mount the directory with this token, specify --remote-path /workspace. A token restricted to /workspace cannot mount the file system root /.
For more information about scoped permissions and credential selection, see Authorization.
Inspect and change token status
For an owner-token-only environment, set TI_FS_TOKEN to the owner token and TI_REGION_CODE to the file system's region before running the commands below. Keep management credentials separate from the scoped token you give to the recipient. A scoped token cannot manage other tokens.
List non-secret metadata for file system tokens:
ti fs list-file-system-tokens \
--file-system-id "<file-system-id>" \
--output text
The output does not include token plaintext. If you lose an owner token, generate a replacement using TiDB Cloud API credentials. You cannot recover the original token by listing tokens.
Use disable-file-system-token to temporarily suspend a token, and enable-file-system-token to restore it.
With owner token authentication, these two commands can change only scoped tokens. To enable or disable an owner token, use TiDB Cloud API credentials, specify --file-system-id, and unset TI_FS_TOKEN so it does not override the API credentials. Do not supply --fs-token for that request. Allow approximately 10 seconds for the change to take effect before verifying access.
Rotate or revoke a token
Use refresh-file-system-token to rotate a file system token.
When you refresh a locally stored token, the CLI automatically updates the local credential. When you refresh a token provided through --fs-token or TI_FS_TOKEN, the CLI returns the new token in the command output without storing it locally.
Before retiring a token, distribute and validate its replacement. Then revoke the old token by its token ID:
ti fs delete-file-system-token \
--file-system-id "<file-system-id>" \
--token-id "<token-id>"
If the deleted token matches the locally stored token, the CLI automatically removes the local credential. Token changes can take time to propagate through authorization caches.
Disabling or revoking an owner token does not automatically revoke scoped tokens generated from it. Review and revoke those scoped tokens separately when necessary.