Admin Role Management

Overview

The Admin Roles API manages roles and permissions for management console users. It supports both built-in and custom roles, enabling fine-grained access control.

Required Permissions

Operation	Required Permission
Read	`admin:admin_roles:read`
Write	`admin:admin_roles:write`

Endpoint List

Method	Endpoint	Description
GET	`/api/admin/admin-roles`	List admin roles
GET	`/api/admin/admin-roles/:id`	Get admin role details
POST	`/api/admin/admin-roles`	Create custom role
PATCH	`/api/admin/admin-roles/:id`	Update role
DELETE	`/api/admin/admin-roles/:id`	Delete role (custom only)
GET	`/api/admin/admin-roles/permissions/list`	List available permissions

List Admin Roles

Retrieve a list of admin roles.

Endpoint

GET /api/admin/admin-roles

Request Example

curl -X GET "https://{tenant-domain}/api/admin/admin-roles" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "items": [
    {
      "id": "role_super_admin",
      "name": "super_admin",
      "display_name": "Super Admin",
      "description": "Administrator with all permissions",
      "is_system": true,
      "hierarchy_level": 100,
      "permissions": ["*"],
      "user_count": 2,
      "created_at": 1705881600000
    },
    {
      "id": "role_admin",
      "name": "admin",
      "display_name": "Admin",
      "description": "General administrative privileges",
      "is_system": true,
      "hierarchy_level": 80,
      "permissions": [
        "admin:admin_users:read",
        "admin:admin_users:write",
        "admin:admin_audit:read"
      ],
      "user_count": 5,
      "created_at": 1705881600000
    },
    {
      "id": "role_viewer",
      "name": "viewer",
      "display_name": "Viewer",
      "description": "Read-only access",
      "is_system": true,
      "hierarchy_level": 10,
      "permissions": [
        "admin:admin_users:read",
        "admin:admin_audit:read"
      ],
      "user_count": 10,
      "created_at": 1705881600000
    }
  ],
  "total": 3
}

Get Admin Role Details

Retrieve detailed information for a specified admin role.

Endpoint

GET /api/admin/admin-roles/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	✓	Role ID

Request Example

curl -X GET "https://{tenant-domain}/api/admin/admin-roles/role_admin" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "role_admin",
  "name": "admin",
  "display_name": "Admin",
  "description": "General administrative privileges",
  "is_system": true,
  "hierarchy_level": 80,
  "permissions": [
    "admin:admin_users:read",
    "admin:admin_users:write",
    "admin:admin_audit:read"
  ],
  "users": [
    {
      "id": "admin_abc123",
      "email": "[email protected]",
      "name": "Admin 1",
      "assigned_at": 1705881600000
    },
    {
      "id": "admin_def456",
      "email": "[email protected]",
      "name": "Admin 2",
      "assigned_at": 1705968000000
    }
  ],
  "user_count": 5,
  "created_at": 1705881600000,
  "updated_at": 1706140800000
}

Create Custom Role

Create a new custom role.

Endpoint

POST /api/admin/admin-roles

Request Body

Field	Type	Required	Description
`name`	string	✓	Role name (alphanumeric and underscores)
`display_name`	string	✓	Display name
`description`	string	-	Description
`permissions`	string[]	✓	List of permissions
`hierarchy_level`	integer	-	Hierarchy level (0-99, default: 50)

Request Example

curl -X POST "https://{tenant-domain}/api/admin/admin-roles" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "audit_viewer",
    "display_name": "Audit Log Viewer",
    "description": "Can only view audit logs",
    "permissions": ["admin:admin_audit:read"],
    "hierarchy_level": 20
  }'

Response Example

{
  "id": "role_audit_viewer",
  "name": "audit_viewer",
  "display_name": "Audit Log Viewer",
  "description": "Can only view audit logs",
  "is_system": false,
  "hierarchy_level": 20,
  "permissions": ["admin:admin_audit:read"],
  "user_count": 0,
  "created_at": 1706227200000
}

Update Role

Update an existing role.

Endpoint

PATCH /api/admin/admin-roles/:id

Request Body

Field	Type	Required	Description
`display_name`	string	-	Display name
`description`	string	-	Description
`permissions`	string[]	-	List of permissions
`hierarchy_level`	integer	-	Hierarchy level

Request Example

curl -X PATCH "https://{tenant-domain}/api/admin/admin-roles/role_audit_viewer" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": [
      "admin:admin_audit:read",
      "admin:admin_users:read"
    ]
  }'

Response Example

{
  "id": "role_audit_viewer",
  "name": "audit_viewer",
  "display_name": "Audit Log Viewer",
  "permissions": [
    "admin:admin_audit:read",
    "admin:admin_users:read"
  ],
  "updated_at": 1706313600000
}

Delete Role

Delete a custom role.

Endpoint

DELETE /api/admin/admin-roles/:id

Request Example

curl -X DELETE "https://{tenant-domain}/api/admin/admin-roles/role_audit_viewer" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "deleted": true,
  "id": "role_audit_viewer"
}

List Available Permissions

Retrieve all available permissions for Admin API.

Endpoint

GET /api/admin/admin-roles/permissions/list

Request Example

curl -X GET "https://{tenant-domain}/api/admin/admin-roles/permissions/list" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "items": [
    {
      "key": "admin:admin_users:read",
      "description": "Read admin users"
    },
    {
      "key": "admin:admin_users:write",
      "description": "Create/update admin users"
    },
    {
      "key": "admin:admin_users:delete",
      "description": "Delete admin users"
    },
    {
      "key": "admin:admin_roles:read",
      "description": "Read admin roles"
    },
    {
      "key": "admin:admin_roles:write",
      "description": "Create/update admin roles"
    },
    {
      "key": "admin:admin_audit:read",
      "description": "Read admin audit logs"
    },
    {
      "key": "admin:ip_allowlist:read",
      "description": "Read IP allowlist"
    },
    {
      "key": "admin:ip_allowlist:write",
      "description": "Manage IP allowlist"
    }
  ],
  "total": 8
}

Permission List

Permission	Description
`admin:admin_users:read`	Read admin users
`admin:admin_users:write`	Create/update admin users
`admin:admin_users:delete`	Delete admin users
`admin:admin_roles:read`	Read admin roles
`admin:admin_roles:write`	Create/update admin roles
`admin:admin_audit:read`	Read admin audit logs
`admin:ip_allowlist:read`	Read IP allowlist
`admin:ip_allowlist:write`	Manage IP allowlist
`*`	All permissions (super admin only)

Hierarchy Level

Hierarchy level determines role priority. Only users with higher-level roles can manage lower-level roles.

Level	Purpose
100	Super Admin (system reserved)
80	Senior Admin
50	General Admin (default)
20	Limited Admin
10	View-only