🔐 How to Fetch User and Group Assignments Across Unity Catalog Workspaces in Databricks

📌 Introduction

As organizations move toward centralized data governance with Databricks Unity Catalog (UC), understanding user and group access across multiple workspaces becomes critical for:

• Access audits
• Compliance reporting
• Cross-team collaboration tracking

But here’s a common misconception:

“If I fetch group and user assignments from a Unity Catalog–enabled workspace, I’ll get info for all workspaces using the same UC.”

❌ Wrong!
Even with Unity Catalog, workspace group assignments are scoped to each workspace individually unless you query using account-level APIs.

This blog explains why this happens, and shows you how to properly fetch group-user mappings across workspaces — both at the workspace level and the account level.

---

🧠 Understanding the Scope

Component	Scope	API to Use
Unity Catalog (catalogs/schemas)	Account-level	GET /accounts/<account_id>/groups
Group-to-user assignments	Workspace-level	GET /api/2.0/preview/scim/v2/Groups
Workspace access (entitlements)	Workspace-level	GET /api/2.0/workspace/<id>/permissions

---

🚧 Common Mistake

You run a group listing query on a Unity Catalog–enabled workspace, expecting it to show group-user relationships for all other workspaces linked to the same UC.

Result: You’ll only get group membership for that specific workspace — not across all.

---

✅ Solution 1: Fetch User-Group Mapping via Workspace SCIM API

Use this method if you only care about one specific workspace.

Python Notebook Example:

# Setup
workspace_url = "https://<workspace>.cloud.databricks.com"
token = "Bearer <your-token>"

# Get Groups
resp = requests.get(f"{workspace_url}/api/2.0/preview/scim/v2/Groups", headers={"Authorization": token})
groups = resp.json()["Resources"]

# Loop through groups and print users
for group in groups:
    print(f"Group: {group['displayName']}")
    for member in group.get("members", []):
        user_id = member["value"]
        # Fetch user details
        user = requests.get(f"{workspace_url}/api/2.0/preview/scim/v2/Users/{user_id}", headers={"Authorization": token})
        print(user.json().get("userName", "Unknown"))

---

✅ Solution 2: Use Unity Catalog Account-Level APIs

Use this method if you want full visibility across all UC-enabled workspaces:

Step-by-step:

1. Generate Account-Level Token
   • Go to accounts.databricks.com → Admin Console → Personal Access Token
2. Use Account SCIM APIs:

GET /api/2.0/accounts/<account_id>/groups
GET /api/2.0/accounts/<account_id>/users

3. Use Workspace Listing API to enumerate which groups are assigned to each workspace:

GET /api/2.0/accounts/<account_id>/workspaces

4. Correlate mappings to build a full picture of which group has access to which workspace or catalog.

---

🧪 Bonus: Cross-Workspace Group Audit Script

Need a script to list all workspaces and users assigned per group?

We can loop like this:

# Pseudo code
for workspace in all_workspaces:
    call /scim/v2/Groups on each workspace
    collect group-user info
combine all into one CSV or Delta table

Let me know if you’d like the full working version of this!

---

📎 Summary

Use Case	Scope	API Required
Audit Unity Catalog access across workspaces	✅ Account-wide	Account-level SCIM + UC Permissions APIs
Check group membership in a workspace	🚫 Local to workspace	SCIM API /Groups in that workspace only
Global group access visibility	✅ Cross-workspace	Requires cross-querying or account token

---

🎯 Summary

Use Case	API Endpoint	Token Scope
Get global UC group-user mappings	https://accounts.databricks.com/api/...	🔐 Account-level PAT
Get group-user assignments per workspace	https://<workspace-url>/api/2.0/preview/scim/...	🔐 Workspace PAT
Get catalog/schema/table access privileges	Unity Catalog permissions APIs	🔐 Account-level PAT

🔚 Final Thoughts

With Unity Catalog, data governance is centralized — but identity management is still workspace-scoped unless accessed via account APIs.

For full visibility across your enterprise data platform, make sure to:

• Use account-level tokens
• Query account-wide group and user APIs
• Document and consolidate group-user relationships regularly

---