1  # Workspace Permissions
  2  
  3  Workspace-scoped permissions provide convenient access control for all resources within a workspace when [authentication](/self-hosting/security/basic-http-auth) is enabled.
  4  
  5  ## Overview
  6  
  7  Workspace permissions allow administrators to grant broad access to groups of resources without managing individual experiment or model permissions. They act as a **fallback**: if a user has no explicit resource-level permission for a resource, MLflow falls back to the workspace permission for that resource's workspace.
  8  
  9  ### Permission Levels
 10  
 11  The same permission levels from MLflow authentication apply at the workspace level:
 12  
 13  | Permission       | Can Read | Can Use | Can Update | Can Delete | Can Manage Permissions |
 14  | ---------------- | -------- | ------- | ---------- | ---------- | ---------------------- |
 15  | `READ`           | Yes      | No      | No         | No         | No                     |
 16  | `USE`            | Yes      | Yes     | No         | No         | No                     |
 17  | `EDIT`           | Yes      | Yes     | Yes        | No         | No                     |
 18  | `MANAGE`         | Yes      | Yes     | Yes        | Yes        | Yes                    |
 19  | `NO_PERMISSIONS` | No       | No      | No         | No         | No                     |
 20  
 21  `USE` is intended for consuming resources without modifying them, such as invoking AI Gateway
 22  endpoints or referencing gateway model definitions and API keys.
 23  
 24  ## How Workspace Permissions Work
 25  
 26  Workspace permissions apply to **all resource types** (experiments, registered models, prompts, and
 27  AI Gateway resources like API keys, model definitions, and endpoints) within a workspace. When a
 28  user has a workspace permission, it grants access to all resources in that workspace.
 29  
 30  ### Example Scenarios
 31  
 32  1. **Workspace-level grant**: `alice` has `READ` permission on workspace `team-a`
 33     - Alice can read all experiments, registered models, and prompts in `team-a`
 34  
 35  2. **Resource-level exception**: `alice` has `NO_PERMISSIONS` on experiment `exp-123` in `team-a`
 36     - Alice can read all resources in `team-a` except `exp-123`
 37  
 38  3. **Direct resource grant**: `bob` has `EDIT` permission on experiment `exp-456` in `team-a` but no workspace permission
 39     - Bob can access only `exp-456`, not other resources in the workspace
 40     - The workspace `team-a` does not appear in Bob's `mlflow.list_workspaces()` results
 41  
 42  ### Permission Resolution Order
 43  
 44  When checking access, MLflow evaluates permissions in the following order:
 45  
 46  1. **Admin check**: Admins have full access to all workspaces
 47  2. **Explicit resource permission**: Directly assigned permissions on the specific resource
 48  3. **Workspace permission**: Permission granted at the workspace level
 49  4. **Default permission**: Used only when workspaces are **disabled**. When workspaces are enabled, the default is effectively **deny** unless a workspace permission (or explicit resource permission) grants access. For the reserved `default` workspace, you can optionally enable `grant_default_workspace_access` to inherit `default_permission`.
 50  
 51  ## Managing Workspace Permissions
 52  
 53  ### Prerequisites
 54  
 55  Workspace permissions require:
 56  
 57  - Workspaces enabled (`--enable-workspaces`)
 58  - Authentication enabled (`--app-name basic-auth`)
 59  - Either admin privileges, or `MANAGE` permission on the workspace to delegate access to others
 60  
 61  ### Permission Delegation
 62  
 63  Users with `MANAGE` permission on a workspace can grant permissions to other users within that workspace. This enables self-service team management without requiring admin intervention.
 64  
 65  ### Using AuthServiceClient
 66  
 67  The Python client mirrors the REST APIs via `mlflow.server.auth.client.AuthServiceClient`. Use
 68  `mlflow.server.get_app_client` to instantiate it after configuring Basic Auth credentials.
 69  
 70  ```python
 71  from mlflow.server import get_app_client
 72  
 73  tracking_uri = "http://localhost:5000"
 74  auth_client = get_app_client("basic-auth", tracking_uri=tracking_uri)
 75  ```
 76  
 77  ### Grant Workspace Permission
 78  
 79  ```bash
 80  curl -X POST http://localhost:5000/api/3.0/mlflow/workspaces/team-a/permissions \
 81    -H "Content-Type: application/json" \
 82    -d '{
 83      "username": "alice",
 84      "permission": "READ"
 85    }'
 86  ```
 87  
 88  Grant full management access:
 89  
 90  ```bash
 91  curl -X POST http://localhost:5000/api/3.0/mlflow/workspaces/team-a/permissions \
 92    -H "Content-Type: application/json" \
 93    -d '{
 94      "username": "bob",
 95      "permission": "MANAGE"
 96    }'
 97  ```
 98  
 99  ```python
100  auth_client.set_workspace_permission(
101      workspace_name="team-a",
102      username="alice",
103      permission="READ",
104  )
105  ```
106  
107  ### List Workspace Permissions
108  
109  Get all permissions for a workspace:
110  
111  ```bash
112  curl http://localhost:5000/api/3.0/mlflow/workspaces/team-a/permissions
113  ```
114  
115  ```python
116  permissions = auth_client.list_workspace_permissions("team-a")
117  ```
118  
119  Get workspace permissions for a specific user (admin only):
120  
121  ```bash
122  curl "http://localhost:5000/api/3.0/mlflow/workspace-permissions?username=alice"
123  ```
124  
125  :::note Response format
126  The API returns `user_id` (the internal user identifier) in responses, not `username`. Use the users API to look up usernames if needed.
127  :::
128  
129  ```python
130  permissions = auth_client.list_user_workspace_permissions("alice")
131  ```
132  
133  ### Revoke Workspace Permission
134  
135  ```bash
136  curl -X DELETE "http://localhost:5000/api/3.0/mlflow/workspaces/team-a/permissions?username=alice"
137  ```
138  
139  ```python
140  auth_client.delete_workspace_permission(workspace_name="team-a", username="alice")
141  ```
142  
143  ## Workspace Visibility in list_workspaces()
144  
145  The `mlflow.list_workspaces()` function returns workspaces based on the following logic:
146  
147  - User must have **workspace-level permission** for the workspace to appear
148  - Direct resource permissions without workspace permissions do **not** grant workspace visibility
149  - Admins see all workspaces
150  - If `grant_default_workspace_access=true`, the reserved default workspace is also visible (and inherits `default_permission`)
151  
152  Example scenario:
153  
154  ```python
155  # alice has workspace permission on team-a
156  # bob has only resource permission on exp-123 in team-a
157  
158  import os
159  import mlflow
160  
161  mlflow.set_tracking_uri("http://localhost:5000")
162  
163  # As alice - provide Basic Auth credentials via environment variables
164  os.environ["MLFLOW_TRACKING_USERNAME"] = "alice"
165  os.environ["MLFLOW_TRACKING_PASSWORD"] = "password"
166  workspaces = mlflow.list_workspaces()
167  print([w.name for w in workspaces])  # ["team-a"] - alice sees the workspace
168  
169  # As bob
170  os.environ["MLFLOW_TRACKING_USERNAME"] = "bob"
171  os.environ["MLFLOW_TRACKING_PASSWORD"] = "password"
172  workspaces = mlflow.list_workspaces()
173  print([w.name for w in workspaces])  # [] - bob doesn't see team-a
174  
175  # But bob can still access the experiment directly if he knows it exists
176  mlflow.set_workspace("team-a")
177  experiment = mlflow.get_experiment("123")  # Works!
178  ```
179  
180  ## Troubleshooting
181  
182  ### Permission Denied Errors
183  
184  If users receive permission denied errors:
185  
186  1. Verify the user has workspace-level permission:
187  
188     ```bash
189     curl "http://localhost:5000/api/3.0/mlflow/workspace-permissions?username=alice"
190     ```
191  
192  2. Check if there's an explicit `NO_PERMISSIONS` on the specific resource
193  
194  3. Verify the workspace exists and the user has access
195  
196  ### Workspace Not Visible in list_workspaces()
197  
198  If a workspace doesn't appear in `mlflow.list_workspaces()`:
199  
200  1. User needs workspace-level permission (resource-level permission is not enough)
201  2. Grant workspace permission:
202  
203     ```bash
204     curl -X POST http://localhost:5000/api/3.0/mlflow/workspaces/team-a/permissions \
205       -H "Content-Type: application/json" \
206       -d '{"username": "user", "permission": "READ"}'
207     ```
208  
209  ## Next Steps
210  
211  - [Configuration](/self-hosting/workspaces/configuration) - Server configuration options
212  - [Workspace Providers](/self-hosting/workspaces/workspace-providers) - Implement custom providers
213  - [Authentication](/self-hosting/security/basic-http-auth) - Set up MLflow authentication