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 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.

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 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.

1
2
3
4
5

{
  "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#

† 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_admins 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.