Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Security and hardening

Azure Databricks REST API returns 403 with a Microsoft Entra token

Error403 User not authorized

Short answer

A 403 means the token was accepted but the identity in it is not allowed in that workspace. Decode the token and check aud, tid and the user or app. Then either add the service principal to the workspace, or send the management token and workspace resource ID headers with an Azure role.

  • Applies to Azure CLI 2.x, Azure Databricks REST API 2.0, curl 8
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Decode the access token you send and read the claims. The docs say aud must be the Databricks resource ID, tid the workspace tenant, and the time must be inside nbf and exp.

    python3 -c "import jwt,sys; print(jwt.decode(sys.argv[1], options={'verify_signature': False}))" "$TOKEN"
  2. 2Match what you see, then jump to its fix

    1. 1aud is not 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d, or tid is not the workspace tenantThe token was requested for the wrong resource or tenantFix
    2. 2aud and tid are right, the app is a service principal, and the call still gives 403The service principal is not a member of the workspaceFix
    3. 3The principal has Contributor or Owner on the workspace resource but is not in the workspace yetThe service principal has an Azure role but the call lacks the management token headersFix
    4. 4unique_name is a user who is not in the workspace, or the current time is outside nbf and expThe user in the token does not exist in the workspace, or the token expiredFix

What does the error look like?

  • 403 User not authorized
  • Error 403 User not authorized when calling the Azure Databricks API

Cause 1 of 4

The token was requested for the wrong resource or tenant

1Check

Print the claims and compare. The token must be issued for the Azure Databricks resource in the tenant that holds the workspace.

az account get-access-token --resource 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d --query accessToken -o tsv

2Fix

Request the token again with the Databricks resource ID (or the scope 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default for the v2 endpoint) after signing in to the right tenant.

az login -t <tenant-id>
az account get-access-token --resource 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d --query accessToken -o tsv

3Verify

A simple call with the new token returns 200 and a JSON body.

curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $TOKEN" https://<databricks-instance>/api/2.0/clusters/list

Confirmed by learn.microsoft.com

Did this fix it?

Cause 2 of 4

The service principal is not a member of the workspace

1Check

Only service principals added to the workspace (through the Service Principals API or the Databricks CLI) can call it with the plain bearer token.

databricks service-principals list

2Fix

Add the service principal to the workspace, or use the Azure role route in the next cause.

databricks service-principals create --application-id <client-id> --display-name "my-pipeline-sp"

3Verify

Call the clusters list again with the same bearer token.

curl -X GET -H "Authorization: Bearer $TOKEN" https://<databricks-instance>/api/2.0/clusters/list

Confirmed by learn.microsoft.com

Did this fix it?

Cause 3 of 4

The service principal has an Azure role but the call lacks the management token headers

1Check

In that case the API needs a second token for Azure Resource Manager and the workspace resource ID in two extra headers.

curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  https://login.microsoftonline.com/<tenant-id>/oauth2/token \
  -d 'client_id=<client-id>' -d 'grant_type=client_credentials' \
  -d 'resource=https%3A%2F%2Fmanagement.core.windows.net%2F' \
  -d 'client_secret=<client-secret>'

2Fix

Send both tokens and the workspace resource ID. After the first successful call the service principal becomes a workspace admin.

curl -X GET \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "X-Databricks-Azure-SP-Management-Token: $MGMT_TOKEN" \
  -H "X-Databricks-Azure-Workspace-Resource-Id: /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Databricks/workspaces/<workspace-name>" \
  https://<databricks-instance>/api/2.0/clusters/list

3Verify

The response is the cluster list, not 403.

# HTTP 200 with a JSON body

Confirmed by learn.microsoft.com

Did this fix it?

Cause 4 of 4

The user in the token does not exist in the workspace, or the token expired

1Check

Compare unique_name with the users of the workspace, and nbf/exp with the clock. Entra access tokens last 60 to 90 minutes by default.

date -u +%s

2Fix

Add the user to the workspace, or request a new token for a user who is already in it.

az account get-access-token --resource 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d --query accessToken -o tsv

3Verify

Repeat the failed call with the fresh token.

curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $TOKEN" https://<databricks-instance>/api/2.0/clusters/list

Confirmed by learn.microsoft.com

Did this fix it?

How do I stop it coming back?

  • Use the Databricks CLI or SDKs with unified authentication, so tokens are fetched and refreshed for you.
  • Add pipeline service principals to the workspace once, and keep their client secret expiry on a calendar.
  • Log the aud, tid and exp claims (not the token itself) when an auth call fails.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.