Unity Catalog Native Authentication

Unity Catalog Native authenticates to the catalog with one of two credentials, chosen with the Type selector in the connection form: an Access Token, or OAuth (Service Principal). Both identify the account Unity Catalog checks every permission against, so the grants described in Permissions are made to that account.

Access Token

The simplest option. Paste a token the catalog issued into the Access Token field and Qualytics sends it with every request to the catalog.

On Databricks, this is a personal access token, generated in the workspace for a user or for a service principal. On an open-source Unity Catalog server, it is the token the server issues for the account Qualytics should use.

An access token has an expiry date set when it is created. When it expires, every datastore on the connection stops reading until a new token is saved on the connection. Prefer a token issued for a service principal over one issued for a person, so that the connection does not break when that person leaves or changes teams.

OAuth (Service Principal)

Qualytics authenticates as a Databricks service principal using its Client ID and Client Secret. Instead of sending a fixed token, Qualytics asks the workspace's token endpoint for a short-lived access token and renews it on its own, so there is no token expiry date to track.

Token Endpoint is optional. When it is empty, Qualytics uses the workspace's own endpoint, which is the URL followed by /oidc/v1/token. Set it only when the server that issues tokens is a different address, as can happen with an open-source Unity Catalog server that delegates sign-in to another system.

What each field does

Field	Required	What it is for
URL		The Databricks workspace URL, for example `https://<workspace>.cloud.databricks.com`, or the URL of an open-source Unity Catalog server.
Type		Access Token, the default, or OAuth (Service Principal). The fields below change with it.
Access Token		Shown for Access Token. The token the catalog issued. Stored encrypted and never displayed back.
Client ID		Shown for OAuth (Service Principal). The service principal's application ID.
Client Secret		Shown for OAuth (Service Principal). The secret generated for that service principal. Stored encrypted and never displayed back.
Token Endpoint		Shown for OAuth (Service Principal). Where Qualytics requests access tokens. Defaults to the URL followed by `/oidc/v1/token`.

What the credential is used for

The credential authenticates Qualytics to the catalog only: listing catalogs and schemas, reading table definitions, and asking for permission to read a table's files. Reading the files themselves uses a separate storage credential that Unity Catalog hands out per table and that lasts about an hour. Your cloud storage keys are never entered in Qualytics and never travel through it.

Because the catalog checks every request against this identity, the token or service principal needs the grants listed in Permissions, including the grant that allows a tool outside Databricks to read a table's files.

How the credentials are stored

The access token and the client secret are stored encrypted and never displayed back to you. Once saved, the field shows that a value is stored rather than the value itself.

To change the token or secret, enter the new one and save.
To keep the stored value while editing anything else on the connection, leave the field empty and save.

The URL, the client ID, and the token endpoint are not secrets and are shown as saved.

Edits apply to every datastore on the connection

Credentials belong to the connection, not to a single datastore. Changing them through Manage Connections changes them for every datastore that reuses that connection.