Skip to main content

Custom URLs

A custom URL gives a customer's Databricks account a single, branded entry point (for example, acme.databricks.com or acme.azuredatabricks.net) that consolidates the account's workspaces under one domain. It is an account-level feature: web users log in once and move between workspaces and Genie One without reauthenticating.

Enabling a custom URL does not change or disable the customer's per-workspace URLs. Existing per-workspace hostnames keep working and remain directly reachable, so partner integrations and bookmarks are unaffected. This page describes how custom URLs affect programmatic access so your integration behaves correctly whether or not a customer has enabled one.

Key principle​

Because a custom URL is account-level, it selects a workspace with a query parameter — ?o=<workspaceId> appended to the standard API path — rather than encoding the workspace in the hostname. A per-workspace hostname needs no selector because the workspace is already implied by the host.

Choosing which host to call​

Both hosts are supported for workspace-scoped APIs. The custom URL is the recommended approach where a customer has enabled one.

API familyHost to callWorkspace selectionNotes
Workspace-scoped (SCIM, Unity Catalog, Serving Endpoints)Custom URL (recommended) or per-workspace URL?o=<workspaceId> required on the custom URL; not needed on the per-workspace URLAuthenticate with an account-issued OAuth token. Personal access tokens are also supported. A workspace-issued OAuth token is rejected on the custom URL
Account ManagementAccount host or custom URLNot applicableThe Account API responds on the custom domain when a custom URL is enabled

API paths are unchanged​

API path structures are identical on the custom domain. Paths such as /api/2.0/preview/scim/v2/ and /api/2.1/unity-catalog/catalogs are unchanged. The only difference on the custom domain is that workspace selection is expressed through the ?o=<workspaceId> query parameter instead of being encoded in the hostname. When you call the per-workspace hostname directly, no selector is required.

The Workspaces API still returns per-workspace URLs​

Enabling a custom URL does not rewrite API responses to the custom domain. The Workspaces API continues to return the standard per-workspace hostname, and that hostname remains directly reachable. Do not assume a response has been rewritten to the custom domain, and do not hardcode the custom domain as the source of truth for a workspace's reachable URL.

OAuth token issuance​

OAuth works through the custom URL. The account-level OAuth token endpoint (/oidc/v1/token) is served on the custom domain, and account-level OIDC discovery resolves there.

When calling workspace-scoped APIs through the custom URL, authenticate with an account-issued OAuth token. Personal access tokens are also supported. A workspace-issued OAuth token — one whose issuer is the per-workspace host — will not be accepted on the custom URL. If workspace-issued tokens are required, send them to the per-workspace URL instead.

Issuer hostname

On the custom URL, account OIDC discovery returns the same account metadata as the account host: the issuer and token endpoint both resolve to accounts.cloud.databricks.com, not the custom-URL host, and account-issued tokens carry that same issuer. Don't hardcode the custom-URL host as the issuer. See OAuth reference for endpoint formats.

Auto-redirect does not affect API calls​

Auto-redirect applies only to browser-based web traffic. When it is enabled, API calls to per-workspace URLs are served directly and are never returned as HTTP 301 or 302 redirects. There is no impact on programmatic access and no risk of authentication headers being dropped or altered by a redirect.

Availability and cloud differences​

Custom URLs are available on AWS, Azure, and GCP, with the following differences and constraints:

  • Domains: Azure custom URLs use the azuredatabricks.net domain; AWS and GCP use the databricks.com domain.
  • GCP: Custom URL ingress and TLS termination currently route through AWS infrastructure. GCP service-account authentication (Google-issued ID tokens) is not supported for workspace API calls made through the custom URL — use the per-workspace URL for that scenario.
  • Unified Login required: Custom URLs require Unified Login.
  • Front-End Private Link: Workspaces that use Front-End (inbound) Private Link fall back to per-workspace URLs.
  • Not supported: SAP Databricks and GovCloud.

Documentation: Enable your custom URL (AWS) | Enable your custom URL (Azure)

What's next​