Skip to main content

​
Credentials

The VFS accesses a Unity Catalog volume through the Databricks Files REST API. Both Python and TypeScript require an explicit workspace host and token. The token can be a personal access token, an OAuth access token, or a callback that supplies the current access token. No extra Python package is required. Obtain a workspace access token. For local testing, you can create a personal access token under Settings → Developer → Access tokens. Scoped tokens need the files API scope.

​
Set the workspace host

Use your workspace origin, such as https://dbc-xxxxxxxx-xxxx.cloud.databricks.com on AWS or https://adb-xxxxxxxxxxxx.xx.azuredatabricks.net on Azure. The host accepts HTTP or HTTPS and rejects a path, query, fragment, or userinfo. A trailing slash is allowed.

​
Find a readable volume

Choose a volume in Catalog Explorer. Its /Volumes/<catalog>/<schema>/<volume>/... path supplies the three config fields. The principal needs USE CATALOG, USE SCHEMA, and READ VOLUME; a write mount also needs WRITE VOLUME. See volume permissions.

​
Supply a token

Pass your token and host to the VFS configuration. For example, your application can read them from environment variables:
Mirage does not discover environment variables, SDK profiles, or default credentials. Your application can use an external SDK or credential broker to obtain a token, then pass the token or a callback to Mirage. A callback owns refresh, caching, and coordination between concurrent requests. Mirage does not retry an unauthorized request with another credential source. Keep each VFS and workspace bound to one principal and permission scope. Isolate file caches, indexes, and external cache prefixes across identities. If the principal or permission scope changes, rebuild the workspace or invalidate its caches. Token refresh for the same principal and scope can use the existing VFS. See the Python Databricks Volume VFS or TypeScript Databricks Volume VFS page for configuration and first-read examples.