Databricks — workspace URL and personal access token¶

This guide walks you through how to find your Databricks workspace URL, generate a personal access token (PAT) with the appropriate API scopes, configure these values, and assign the necessary Assets and data permissions so your integrations can securely authenticate and interact with Genie and AI Agent resources.

Prerequisites¶

1. Workspace URL (DATABRICKS_HOST)¶

What it is: The base URL of your workspace — the same value you use in the browser to open Databricks.

Steps¶

1. Sign in to Databricks (your organization’s workspace URL).
2. Open the workspace in the browser.
3. From the address bar:
   • Keep: https:// and the hostname only.
   • Drop: any path after the host (for example /browse, /?o=...).

Examples¶

• AWS: https://dbc-xxxxxxxx.cloud.databricks.com or https://<workspace-name>.cloud.databricks.com
• Azure: often https://adb-<digits>.<region>.azuredatabricks.net

Read more: Workspace instance names, URLs, and IDs.

2. Personal access token (DATABRICKS_TOKEN)¶

What it is: A personal access token (PAT). It lets the Databricks SDK or REST clients act as your user, with your workspace permissions.

Steps in the workspace UI¶

1. While signed in, open the user menu (avatar, top right) → Settings.
2. Go to Developer -> Access tokens -> Manage(wording can vary by deployment; see the PAT documentation for your cloud).
3. Choose Generate new token.
4. Optional: set a comment and lifetime (days until expiry).
5. Under Scope selection, choose Other APIs (not BI Tools).

6. In API scope(s), add all of the scopes below — they are required for Trust3 to integrate with Databricks correctly.

   API scope
   access-management
   apps
   clusters
   custom-llms
   genie
   jobs
   knowledge-assistants
   mlflow
   model-serving
   scim
   sql
   supervisor-agents
   unity-catalog
   vector-search

   mlflow and scim are required when trace collection is enabled (TRACE_COLLECTION_ENABLED=true) — for MLflow traces and for resolving user identities in trace metadata.

   Note

   If required scopes are not visible in the API scopes list, create the token using all APIs.

7. Click Generate, then copy the token once when it is shown; it often starts with dapi.

Read more: Authenticate with personal access tokens
Azure deployments: Azure Databricks — PAT

3. Map values to configuration¶

Example:¶

1
2
3

DATABRICKS_HOST=https://your-workspace-hostname
DATABRICKS_TOKEN=dapixxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
DATABRICKS_ENVIRONMENT_NAME=(dev/test/prod/stage)

4. Assets permissions (minimum)¶

The user who creates the PAT (or the identity associated with the token) must have adequate access to the relevant Databricks assets. Ensure the required permissions are granted through the workspace Assets UI—for example, via each asset's Share or Permissions settings (labels may vary depending on the interface).

Genie space¶

Grant Unity Catalog access (for example SELECT on every table and view attached to the space) so the user can read the same data the Genie space is built on. Databricks notes that Genie may query additional tables permitted by UC, not only those explicitly added to the space — align grants with your security model. See Manage data objects.

Model usage traces — SQL warehouse and system catalog¶

When trace collection is enabled, the collector also reads Databricks system tables to ingest foundation model (ai_query) and custom serving endpoint usage into Trust3 usage summaries. Model usage collection is on by default (collector.databricks.model-usage.enabled=true, env: DATABRICKS_MODEL_USAGE_ENABLED=true). Set either property to false if you do not want this data.

The collector runs these queries through the Databricks SQL Statements API. You need one SQL warehouse the collector identity can use, plus Unity Catalog access to the system catalog.

1. SQL warehouse — permission and HTTP path¶

How to find the SQL warehouse HTTP path

1. In the Databricks workspace, click SQL Warehouses.
2. Click the warehouse you want the collector to use (create one if needed — e.g. a small Serverless warehouse).
3. Open Connection details (or the warehouse Configuration tab).
4. Copy the full HTTP path using the copy button (for example /sql/1.0/warehouses/eead5eea05a19b3e). The collector parses the warehouse ID from this path — you do not need to extract the ID manually.

See Get connection details for a Databricks compute resource for Databricks' step-by-step instructions.

Example configuration

1
2
3
4
5
6
7

# Docker / .env
DATABRICKS_MODEL_USAGE_ENABLED=true
DATABRICKS_SQL_WAREHOUSE_HTTP_PATH=/sql/1.0/warehouses/eead5eea05a19b3e

# Runtime collector properties (equivalent)
# collector.databricks.model-usage.enabled=true
# collector.databricks.sql-warehouse-http-path=/sql/1.0/warehouses/eead5eea05a19b3e

Grant Can Use on that warehouse: SQL Warehouses → [your warehouse] → Permissions → add the PAT user or principal → Can Use.

2. system catalog — table permissions¶

Grant the collector principal read access to the system catalog schemas and tables below. A metastore admin (or account admin) usually runs these grants.

1
2
3
4
5
6
7
8
9

-- Catalog / schema access
GRANT USE CATALOG ON CATALOG system TO `<collector-principal>`;
GRANT USE SCHEMA ON SCHEMA system.ai_gateway TO `<collector-principal>`;
GRANT USE SCHEMA ON SCHEMA system.serving TO `<collector-principal>`;

-- Table SELECT (model usage collectors)
GRANT SELECT ON TABLE system.ai_gateway.usage TO `<collector-principal>`;
GRANT SELECT ON TABLE system.serving.endpoint_usage TO `<collector-principal>`;
GRANT SELECT ON TABLE system.serving.served_entities TO `<collector-principal>`;

Replace <collector-principal> with the principal application ID or user name associated with your PAT/OAuth identity.

Read more: System tables · SQL warehouse permissions

AI Agent¶

Summary¶

Official documentation (quick links)¶