Optimove Zero Copy reads data directly from your Databricks SQL warehouse using a dedicated service principal that authenticates with OAuth machine-to-machine (M2M) credentials. This guide covers the prerequisites your team completes in Databricks before the connection can be established: creating the service principal, granting workspace and Unity Catalog permissions, collecting the connection attributes, and verifying the setup.

This is a one-time setup performed by a Databricks administrator on your workspace. No customer data leaves your Databricks environment during these steps.

Prerequisites

• A Databricks workspace with Unity Catalog enabled
• Account admin access — required to create service principals in the Account Console
• Workspace admin access — required to manage entitlements and SQL Warehouse permissions
• A SQL Warehouse provisioned (Serverless, Pro, or Classic)
• The target catalog, schema, and table already created and populated
• Outbound connectivity over HTTPS (port 443) — no additional port configuration is required

Connection Attributes

Collect the following values before you configure the connection in the Optimove platform.

Step 1: Create a Service Principal

1. Go to your Databricks Account Console — the account-level admin console, not the workspace.
2. Navigate to User management > Service principals.
3. Click Add service principal and give it a descriptive name, for example optimove-zero-copy.
4. Note the Application ID (UUID) — this is your client_id.

Step 2: Generate the OAuth Client Secret

1. In the Account Console, select the service principal you created.
2. Open the Secrets tab.
3. Click Generate secret.
4. Copy and securely store both the Client ID and the Client Secret.

Step 3: Assign the Service Principal to the Workspace

The service principal is created at the account level. It must be explicitly added to the target workspace and granted the required entitlements.

1. In the Account Console, go to User management > Service principals.
2. Select your service principal.
3. Open the Workspaces tab and verify the service principal is assigned to the workspace where your data resides. If it is not, click Add to workspace and select the target workspace.
4. Under Workspace entitlements, enable:
   • Workspace access
   • Databricks SQL access

Step 4: Grant SQL Warehouse Access

The service principal needs CAN USE permission on the SQL Warehouse. This is configured through the workspace UI, not via SQL.

1. Open your Databricks Workspace.
2. Navigate to SQL Warehouses in the left sidebar.
3. Select the warehouse you want Optimove to use.
4. Open the Permissions tab.
5. Add the service principal and grant Can Use.

Step 5: Grant Unity Catalog Permissions

Run the following in the Databricks SQL Editor. Replace the placeholders with your actual catalog, schema, and service principal name.

Grant catalog access:

GRANT USE CATALOG ON CATALOG `your_catalog` TO `optimove-zero-copy`;

Grant schema access:

GRANT USE SCHEMA ON SCHEMA `your_catalog`.`your_schema` TO `optimove-zero-copy`;

Grant read access on tables:

-- Grant SELECT on all current tables in the schema
GRANT SELECT ON SCHEMA `your_catalog`.`your_schema` TO `optimove-zero-copy`;

GRANT SELECT ON TABLE `your_catalog`.`your_schema`.`your_table` TO `optimove-zero-copy`;

Step 6: Collect the Host and HTTP Path

1. In your Databricks Workspace, go to SQL Warehouses.
2. Select the warehouse Optimove will connect to.
3. Open the Connection Details tab.
4. Copy:
   • Server hostname → the host value
   • HTTP path → the http_path value

Step 7: Verify the Setup

Confirm the grants are in place before testing the connection.

Check grants on catalog:

SHOW GRANTS ON CATALOG `your_catalog`;

Check grants on schema:

SHOW GRANTS ON SCHEMA `your_catalog`.`your_schema`;

Check grants for service principal:

SHOW GRANTS TO `optimove-zero-copy`;

Step 8: Test the Connection in Optimove

Once all steps are complete, run the connection test in the Optimove platform's Zero Copy configuration. The test validates:

1. Network connectivity and authentication to the workspace
2. Access to the specified catalog (USE CATALOG)
3. The ability to execute queries on the SQL warehouse

Step 9: Configure the IP Access List

Apply network restrictions after you have confirmed the connection works in Step 8.

If your Databricks workspace has IP Access Lists enabled, you must allowlist Optimove's IP addresses.

1. In your Databricks Workspace, go to Settings > Security > IP Access Lists.
2. Add all Optimove IP addresses for your region — US or EU.
3. Find the full list on the IP Allow List page.

Permissions Summary

Alternative: Personal Access Token (PAT)

If OAuth M2M is not available in your environment, you can authenticate with a Personal Access Token instead.

To generate a PAT for a user:

1. In the Databricks Workspace, click your user icon in the top right.
2. Go to Settings > Developer.
3. Click Manage next to Access tokens.
4. Click Generate new token.
5. Set a description and an expiration (maximum 730 days), then copy the token.

To generate a PAT for a service principal, use the REST API:

curl -X POST "https://YOUR_HOST/api/2.0/token-management/on-behalf-of/tokens" -H "Authorization: Bearer ADMIN_PAT" -H "Content-Type: application/json" -d '{"application_id": "SERVICE_PRINCIPAL_APP_ID", "comment": "Optimove ZCL", "lifetime_seconds": 7776000}'

When using a PAT, provide the token value instead of client_id and client_secret. All of the catalog, schema, and table grants in Step 5 are still required — the PAT inherits permissions from the identity it was generated for.

Troubleshooting