Skip to main content
Select Actions to adjust the guide
Some actions may require additional configuration in the provider to be accessible. Choose the actions you need and the guide will be updated.
Action
Scope(s)
Loading actions…
Dynamic Guide URL
Scopes Selected
Separator
You must have Databricks workspace admin privileges to create service principals, generate OAuth secrets, and grant workspace-object permissions.


​
Finding Your Workspace URL
The Workspace URL is the hostname of your Databricks workspace (without https://).
1
Sign in to Databricks
Open the Databricks Account Console in a browser (or your cloud-specific equivalent — Azure or GCP) and sign in as a workspace admin. If you already know your workspace URL you can also navigate to it directly; typical formats are https://<workspace-hostname>.cloud.databricks.com (AWS), https://adb-<id>.<n>.azuredatabricks.net (Azure), or https://<id>.<region>.gcp.databricks.com (GCP).
2
Select your workspace
After sign-in you may land on a Select a workspace screen at accounts.cloud.databricks.com/select-workspace?account_id=... (Free Edition / multi-workspace accounts). Click the row for the workspace you want to integrate (e.g. workspace). The browser will then redirect to that workspace’s URL — this is the workspace URL you need.
3
Copy the Workspace Hostname
Look at the URL bar. Your workspace URL is the hostname between https:// and the first / — for example dbc-e5d7119f-c9fa.cloud.databricks.com or adb-1234567890123456.7.azuredatabricks.net. Paste this value (without https:// and without a trailing slash) into the Workspace URL field in StackOne.


​
Creating a Service Principal
A service principal is a machine identity used for automated API access without tying credentials to a user account.
1
Open Workspace Settings
Click your user avatar in the top-right corner of the workspace. A dropdown appears — click Settings from that dropdown.
2
Navigate to Service Principals
In the Settings sidebar select Identity and access, then click Manage next to Service principals.
3
Add a Service Principal
Click Add service principal. A dialog opens with a dropdown to select an existing service principal and an Add new button — click Add new to create a new one. In the Service principal name field, enter a descriptive name (e.g. “StackOne Integration”), then click Add. Note the Application ID (UUID) shown on the service principal details page — you will need it later for granting workspace permissions.
4
Confirm Status and Required Entitlements
On the service principal details page, open the Configurations tab. You will see two separate sections — Status and Entitlements (each with its own heading). First, in the Status section, confirm the Active checkbox is selected. Then, in the Entitlements section directly below it, confirm the following entitlements are enabled (the portal lists them in this order)
  • Databricks SQL access — required for SQL warehouse and statement execution actions
  • Workspace access — required to use the workspace at all
5
Save the Changes
If you changed any of the checkboxes, click Update at the bottom of the Configurations tab to persist the changes.


​
Generating OAuth Credentials
Generate an OAuth client secret for the service principal to use with the client credentials flow.
1
Open the Secrets Tab
Still on the service principal details page, click the Secrets tab.
2
Generate a Secret
Click the Generate secret button. A Generate OAuth secret popup appears with a field labelled Lifetime (days). Enter a whole number between 1 and 730 in the text input, then click the blue Generate button.
3
Copy the Credentials
Copy both values immediately — the secret is shown only once and cannot be retrieved later.
  • Client ID — paste into the Client ID field in StackOne
  • Client Secret — paste into the Client Secret field in StackOne


​
Selecting Scopes
Scopes are entered only on the StackOne Hub link-account page — there is no scope selection step on the Databricks side.
1
Choose your scopes
Enables actions: Cancel Job Run, Cancel SQL Statement, Check Table Exists, Create Catalog, Create Cluster, Create Job, Create SQL Warehouse, Create Schema, Create Workspace Directory, Delete Catalog, Delete Job, Delete SQL Warehouse, Delete Schema, Delete Table, Delete Workspace Object, Edit Cluster, Edit SQL Warehouse, Execute SQL Statement, Export Workspace Object, Get Catalog, Get Cluster, Get Job, Get Job Run, Get Job Run Output, Get SQL Statement, Get SQL Warehouse, Get Schema, Get Table, Get Workspace Object Status, Import Workspace Object, List Catalogs, List Clusters, List Job Runs, List Jobs, List Node Types, List SQL Warehouses, List Schemas, List Spark Versions, List Table Summaries, List Tables, List Workspace Objects, Permanently Delete Cluster, Restart Cluster, Run Job, Start Cluster, Start SQL Warehouse, Stop SQL Warehouse, Terminate Cluster, Update Catalog, Update Job, Update Schema
In the StackOne Hub, the Scopes field defaults to all-apis if left empty. To restrict access, enter individual scopes separated by spaces. If you use a custom scope list, clusters is required (the connection test action list_clusters needs it) — add jobs, sql, workspace, and/or unity-catalog alongside it for the resources you intend to use.


​
Granting Workspace-Object Permissions
By default, the service principal has full permissions only on its own home directory /Users/<application-id>/. For workspace-write actions (create_workspace_directory, import_workspace_object, delete_workspace_object) targeting any other path, a workspace admin must explicitly grant the service principal Can Edit (or Can Manage) on the target parent directory. For read actions targeting paths outside the SP home, at least Can Read is required.
1
Open the Workspace Browser
Click Workspace in the left sidebar. Select the target folder row (or the workspace root Workspace for broad access — permissions on the root inherit to all sub-paths).
2
Open the Sharing Dialog
Click the Share button at the top-right of the page. A Sharing modal opens.
3
Add the Service Principal
Remove any default All workspace users chip from the search field if present. In the search field, type either the service principal’s display name OR its Application ID (UUID) — both resolve. The autocomplete dropdown will show matching service principals with their Application IDs; click the entry corresponding to your service principal to select it as a chip in the search field.
4
Set Permission Level and Save
Use the permission-level dropdown next to the principal to choose a level. The portal labels are Can Read, Can Run, Can Edit, and Can Manage (the underlying API values are CAN_READ, CAN_RUN, CAN_EDIT, and CAN_MANAGE respectively). For the StackOne integration to perform both read and write workspace actions, select Can Manage (recommended — also allows the principal to grant permissions to others). Click Add. Permissions on the workspace root inherit to all sub-paths.


​
Linking the Account from the Hub
1
Navigate to the Hub
Use one of the three Linking Account Methods to access the Hub.
2
Fill out the fields
Fill out the following fields using details from your provider:
  • Workspace URL
  • Client ID
  • Client Secret
  • Scopes (Optional)
3
Connect
  • Click Connect
  • If applicable, the provider will redirect you to a sign-in or authorization page. Complete the provider’s authorization flow.
  • Once authorization is successful, you will see a confirmation popup
If the account linking is successful, you will see the newly linked account in your Accounts page.