Access API
Grant workspace-site roles Data Vault collections, workspace-wide Files, and Apps launch.
Workspace Access is how site roles (from workspace auth) get Vault, Files, and Apps. Portal Team stays on workspace SpiceDB. M2M is not an Access subject.
See also: Customer Portal — Access
Built-in site admin already has full Vault, Files, and Apps. Do not grant admin here.
Get Access
GET /v1/workspaces/{workspace_id}/accessPermission: read
{
"workspace_id": "<uuid>",
"roles": [
{ "name": "viewer", "builtin": true },
{ "name": "user", "builtin": true },
{ "name": "admin", "builtin": true }
],
"apps": [
{ "id": "<app uuid>", "name": "Billing", "visibility": "workspace" }
],
"vault_grants": [
{ "role": "user", "collection": "orders", "action": "write" }
],
"files_grants": [
{ "role": "user", "action": "read" }
],
"app_grants": [
{ "role": "user", "app_id": "<app uuid>", "action": "read" }
]
}| Field | Meaning |
|---|---|
vault_grants | Per collection. action is read | write | delete |
files_grants | Workspace-wide (every file). action is read | write |
app_grants | Launch on the Shell. action is always read |
apps[].visibility | workspace if every non-admin site role can launch; otherwise restricted |
If Groundfloor login is not enabled, roles falls back to builtin viewer / user / admin.
Replace Access
PUT /v1/workspaces/{workspace_id}/accessPermission: ddl
Body is a full replace of the grant lists you send:
{
"vault_grants": [
{ "role": "user", "collection": "orders", "action": "write" }
],
"files_grants": [
{ "role": "user", "action": "read" }
],
"app_grants": [
{ "role": "user", "app_id": "<app uuid>", "action": "read" }
]
}| Field | If omitted |
|---|---|
vault_grants | Treated as [] — collections with no remaining site-role grants go admin-only |
files_grants | Treated as [] |
app_grants | null / omitted — leave Apps unchanged. Send [] to restrict every product app |
Vault PUT preserves workload-identity grants on each collection. Site admin is implicit and is ignored if present in app_grants.
If every non-admin catalog role has launch on an app, visibility stays workspace. Removing a role makes it restricted.
Collection shortcut
Per-table Vault grants also exist on the Data Vault API:
GET /v1/workspaces/{workspace_id}/vault/collections/{name}/acl
PUT /v1/workspaces/{workspace_id}/vault/collections/{name}/aclPermission: read / ddl
See Data Vault API — Collection Access.