Skip to content

Databricks setup

To add a Databricks workspace to the AI Assets Collector you need:

  • A Databricks account with access to the workspace, and the workspace reachable over HTTPS.
  • Your workspace URL — section 1.
  • An authentication method — section 2, and each method has its own setup page.
  • The asset and data permissions for the identity the collector uses — section 3.

Optionally, model usage traces for foundation model and serving endpoint usage.

1. Workspace URL

The base URL of your workspace — the same value you use in the browser to open Databricks. It goes in the collector's Databricks host field.

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. Choose an authentication method

The collector's Authentication method dropdown offers four options. Picking one shows only that method's credential fields and hides the others.

Each option has its own setup page:

Authentication method Cloud Use it when
Personal access token (default) Any Getting started or a short evaluation. Tied to a user.
Service principal (OAuth M2M) Any Production. No user dependency.
Entra ID service principal (Azure only) Azure The same identity must reach other Azure resources, or credentials must live in Entra ID.
Entra ID workload identity (Azure AKS only) Azure AKS You want no stored secret at all.

3. Assets permissions (minimum)

Who to grant to

Grant everything below to the identity the collector authenticates as — called the collector identity on this page:

  • Any service principal method — the service principal. Search for it by the name you gave it, or by its application (client) ID.
  • Personal access token — the user who created the token.

Tip

If you gave a service principal Admin access when you added it, the workspace-asset grants below are already covered. The Unity Catalog grants are separate and still required.

How to grant a workspace asset permission

The same three steps for every workspace asset:

  1. Open the asset in the Databricks workspace.
  2. Click Permissions (labelled Share on Genie spaces).
  3. Search for the collector identity, choose the level from the table below, then Add and Save.

How to grant Unity Catalog access

  1. Open SQL Editor in the workspace (or use a notebook).
  2. Paste the GRANT statements, replacing the principal with the collector identity.
  3. Run them as a metastore admin, account admin, or the object's owner.

What to grant

Asset Level Where to set it
Genie space Can Manage Genie → your space → Share
AI Agent Can Manage Open the agent where it is deployed — Serving, Apps or Agents — then Permissions
SQL warehouse used for usage queries Can Use See Model usage traces
Tables and views a Genie space reads SELECT SQL Editor (Unity Catalog grant)
system catalog usage tables USE CATALOG, USE SCHEMA, SELECT See Model usage traces

Notes on the two Can Manage grants:

  • Genie space — matches CAN MANAGE in the Databricks access control lists.
  • AI Agent — when agents run as Databricks Apps, their tools may need their own grants, for example Can Run on a Genie space used as a tool. See Authentication for AI agents.

On Genie data access: a Genie space may query any table Unity Catalog permits, not only those attached to the space. Align the SELECT grants with your security model rather than copying the space's attached-table list. See Manage data objects.

What's next — model usage traces (optional)

Once the workspace is connected, the collector can also summarize model usage — foundation model calls and custom serving endpoint invocations — by reading Databricks system tables.

It is optional and independent of everything above:

  • Skip it and the rest of the collector works normally; you simply get no usage summaries.
  • Enabling it needs one SQL warehouse and a few system catalog grants.

If that is useful to you, see Model usage traces.