---
summary: ScaiMind module permissions and which roles get them by default.
title: Permissions
path: reference/permissions
status: published
---

ScaiMind defines four module-permission keys, mapped onto ScaiGrid's RBAC system. Every endpoint and admin page enforces one of them.

## Permission keys

| Key | What it grants |
|---|---|
| `scaimind:view` | List and read jobs, metrics, logs, evaluations, queue, cluster status, nodes. The Training Dashboard and Training Monitor admin pages. |
| `scaimind:manage` | Submit, cancel, pause, resume, retry jobs; validate data sources; inspect data cache. The Job Creator admin page. |
| `scaimind:cluster_admin` | Drain and enable cluster nodes. The Hardware Monitor admin page. |
| `scaimind:evaluate` | Submit and read evaluations. The Evaluation Center admin page. |

## 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. |
| `tenant_user` | None by default. |
| `tenant_viewer` | `scaimind:view`. |

Training affects GPU spend, scheduling priority, and produces artefacts that can be promoted to backends — so `tenant_user` is explicit opt-in via a custom role.

## Granting selectively

Typical custom-role split:

- **ML engineers** — `scaimind:view`, `scaimind:manage`, `scaimind:evaluate`. Can do everything except touch the cluster topology.
- **Platform / infra** — `scaimind:view`, `scaimind:cluster_admin`. Drain nodes for maintenance, watch hardware, but don't submit jobs.
- **Researchers / viewers** — `scaimind:view`. Read jobs and dashboards, no mutations.

Create a custom role through `/v1/iam/custom-roles` with the appropriate `module_permissions` array, then map a group to it:

```bash
curl -X POST "$SCAIGRID_HOST/v1/iam/custom-roles" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ML engineer",
    "module_permissions": [
      "scaimind:view",
      "scaimind:manage",
      "scaimind:evaluate"
    ]
  }'
```

A separate "cluster operator" role with `scaimind:cluster_admin` is usually held by fewer people — drains and force-aborts affect every tenant on the cluster.

## Endpoint to permission mapping

| Endpoint group | Permission |
|---|---|
| `GET /jobs`, `GET /jobs/{id}`, `GET /jobs/{id}/metrics*`, `GET /jobs/{id}/logs`, `GET /queue`, `GET /cluster`, `GET /cluster/nodes*`, `GET /evaluations*` | `scaimind:view` |
| `POST /jobs`, `POST /jobs/{id}/{cancel,pause,resume,retry}`, `POST /data/validate`, `GET /data/cache` | `scaimind:manage` |
| `POST /cluster/nodes/{id}/drain`, `POST /cluster/nodes/{id}/enable` | `scaimind:cluster_admin` |
| `POST /evaluations`, `GET /evaluations/{id}` | `scaimind:evaluate` |

## Audit

Every permission-gated call carries the standard `actor_user_id`, `action`, `resource_id`. ScaiGrid's audit-log query supports `module=scaimind` as a filter. Lifecycle controls (cancel, pause, resume, retry, drain, enable) are the most useful events to alert on.