---
title: Admin Roles and Permissions
path: concepts/admin-roles
status: published
---

# Admin Roles and Permissions

ScaiKey uses a three-tier admin role model. Each role grants a different scope of access to the admin API.

---

## Roles

### super_admin

Full access to every resource on the platform. Can manage partners, tenants, applications, users, groups, and other admins. Can view audit logs and configure system-wide settings.

There must always be at least one super_admin.

### partner_admin

Scoped to a single partner. Can manage applications, users, and groups across **all of that partner's tenants**. Can also create, update, and delete tenants under their partner — **but only when the partner has [tenant self-management](#tenant-self-management) enabled** (a super-admin toggle); otherwise tenant management is super-admin-only. Can **read its own partner** record (to see its `max_tenants` quota and settings) and **appoint or revoke `TENANT_ADMIN`** for tenants in its own partner. Cannot see or modify resources belonging to other partners, cannot create or delete partners, and cannot mint `super_admin`/`partner_admin` roles.

### tenant_admin

Scoped to a single tenant. Can manage users, groups, and application assignments within that tenant. Cannot access other tenants or partner-level resources.

---

## Role Assignment

Admin roles are stored in the `admin_roles` table. Each record links a user to a role and, where applicable, to a partner or tenant.

| Field | Description |
|---|---|
| user_id | The user who holds the role. |
| role | One of `super_admin`, `partner_admin`, `tenant_admin`. |
| partner_id | Required for `partner_admin`. The partner this admin manages. |
| tenant_id | Required for `tenant_admin`. The tenant this admin manages. |

A user can hold multiple roles (e.g. `tenant_admin` for two different tenants).

---

## Admin Roles API

Base URL: `https://scaikey.scailabs.ai/api/v1/admin/admin-roles`. See the [Admin Roles API reference](/docs/scaikey/reference/api/admin-roles) for full details.

A `super_admin` can manage every assignment. A `partner_admin` can **assign and revoke `TENANT_ADMIN`** for tenants under its own partner (this is how a partner seats the first Tenant Admin of a tenant it provisioned); it cannot assign `super_admin`/`partner_admin`, touch another partner, or edit an existing assignment (`PATCH` is super-admin-only).

### GET /

List admin role assignments. Supports filtering by `user_id`, `role`, `partner_id`, and `tenant_id`. A `partner_admin` sees only assignments within its own partner.

### POST /

Create a new admin role assignment.

```json
{
  "user_id": "usr_123",
  "role": "TENANT_ADMIN",
  "tenant_id": "tnt_456"
}
```

### GET /{id}

Retrieve a single role assignment.

### PATCH /{id}

Update a role assignment (`super_admin` only).

### DELETE /{id}

Remove a role assignment. Returns 204 on success. The system prevents deleting the last `super_admin` role.

---

## Permission Matrix

| Action | super_admin | partner_admin | tenant_admin |
|---|---|---|---|
| Manage partners | Yes | Read own only | No |
| Manage tenants | All | Own partner † | No |
| Manage applications | All | Own partner | No |
| Manage users | All | Own partner's tenants | Own tenant |
| Manage groups | All | Own partner's tenants | Own tenant |
| Manage admin roles | All | `TENANT_ADMIN` in own partner | No |
| View audit logs | All | Own partner's tenants | Own tenant |
| Manage webhooks | Yes | No | No |
| Revoke sessions | All | Own partner's tenants | Own tenant |

**†** Tenant management for a partner admin requires the partner's
**tenant self-management** flag (see below). Without it, tenant create/update/delete
is super-admin-only.

Audit logs and sessions are scoped exactly as shown: a partner admin sees only
entries for tenants under their partner (platform-level audit entries with no
tenant are super-admin-only), and a tenant admin only their own tenant. This
whole table reflects the deployed behaviour.

---

## Tenant self-management

By default, only super-admins create, update, or delete tenants. A super-admin can
delegate this to a **partner's** admins with a per-partner switch, so partners
provision their own tenants without going through the platform operator.

- **Enable it:** in the admin console, open **Partners → (partner) → Edit** and turn
  on **"Allow tenant self-management"**; or via the API,
  `PATCH /api/v1/admin/partners/{id}` with
  `{"settings": {"allow_tenant_self_management": true}}` (super-admin only).
- **What it grants:** that partner's `partner_admin`s may create/update/delete
  tenants **under their own partner only** — `partner_id` is pinned server-side, so
  they cannot target another partner — up to the partner's `max_tenants` quota.
- **When it's off:** partner admins get `403 "Tenant self-management is not enabled
  for this partner"` on tenant writes.

Setting the flag is always super-admin-only; a partner admin cannot enable it for
their own partner.