---
summary: ScaiBunker module permissions, what each one grants, and which roles get
  them by default.
title: Permissions
path: reference/permissions
status: published
---

ScaiBunker defines its own module-permission keys, mapped onto ScaiGrid's RBAC system. Every endpoint enforces one of them.

## Permission keys

Every endpoint enforces one of these keys; granting a key admits the caller to exactly the operations it lists. Network profiles and lifecycle modes each have their own permission so you can grant precise postures without overprovisioning.

| Key | What it grants |
|---|---|
| `scaibunker:create` | Create ephemeral bunkers, list and read your own bunkers, read images and availability groups, read your own quota usage. |
| `scaibunker:create:session` | Create session-scoped bunkers (bound to a logical session). |
| `scaibunker:create:persistent` | Create persistent bunkers (bound to ScaiCore entities). |
| `scaibunker:execute` | Run commands in bunkers you own. |
| `scaibunker:shell` | Open the interactive WebSocket PTY shell. |
| `scaibunker:files` | Read, write, list, delete files inside bunkers you own. |
| `scaibunker:root` | Run commands as root inside the bunker. |
| `scaibunker:network:registry` | Use the `registry` network profile. |
| `scaibunker:network:allowlisted` | Use the `allowlisted` network profile. |
| `scaibunker:network:unrestricted` | Use the `unrestricted` network profile. |
| `scaibunker:network:transit` | Use the `transit` network profile (L2 bridge attaches). |
| `scaibunker:l2_transparency` | Disable `spoof_guard` on transit interfaces. Always audit-logged. |
| `scaibunker:images:manage` | Register, deactivate, scan, and warm images; mint storage capabilities. |
| `scaibunker:admin` | List all bunkers across the platform; drain/resume workers; manage bridges. |
| `scaibunker:admin:tenant` | Manage tenant-scoped quota profiles and availability groups for your tenant. |
| `scaibunker:admin:platform` | Platform-level administration: platform-default quota profiles, platform availability groups, all-tenants worker management. |

## Default role mapping

Built-in roles auto-grant these via ScaiGrid's catch-all in `CurrentUser.has_module_permission`:

| Role | Auto-grants |
|---|---|
| `super_admin` | All of the above. |
| `partner_admin` | All of the above for tenants under the partner. |
| `tenant_admin` | All of the above for the tenant, except `scaibunker:admin:platform`. |
| `tenant_user` | None by default — explicit opt-in. |
| `tenant_viewer` | Read-only access via `scaibunker:create`-equivalent listing scope (no actual create). |

`tenant_user` gets nothing automatically because bunkers consume compute and the network profiles open real risk — you want each operator's network posture to be deliberate, not inherited.

## Granting selectively

Most tenants stand up two or three custom roles:

- **Bot operators.** `scaibunker:create`, `scaibunker:execute`, `scaibunker:files`, `scaibunker:shell`, `scaibunker:network:registry` — can run real workloads but only ever talk to package mirrors.
- **Allowlisted-network agents.** Above plus `scaibunker:network:allowlisted`. The bunker creator sets the allowlist per bunker.
- **Image maintainers.** `scaibunker:images:manage` — separate from the operators, usually held by a smaller group.

Unrestricted, transit, and L2-transparency are deliberately separate keys; grant them only to identities that need exactly that posture.

## Embed-token equivalent

ScaiBunker has no embed-token concept. Every call to the API is on the caller's own bearer token; bunkers themselves only have the controller backchannel (not user-callable). If you need a per-conversation sandbox driven by a downstream service, mint a ScaiKey service-account credential with the narrower set of `scaibunker:*` permissions, not a long-lived user token.

## Audit

Every permission-gated call is logged with `actor_user_id`, `action`, `resource_id`. ScaiGrid's audit log query supports filtering by `module = "scaibunker"`:

```bash
curl "$SCAIGRID_HOST/v1/audit/events?module=scaibunker&since=2026-05-01" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY"
```