---
title: "Create Role"
method: POST
path: "/api/admin-role"
tags: ["Admin Roles"]
---

# Create Role

`POST /api/admin-role`

Create a new role. Owner only.

## Request body

- AdminRoleCreate
  - `name` string, required
  - `permissions` RolePermissions — Typed permission map. Missing resource or action = denied. Each action value is True (allowed), {"scope": N} (scoped), or None (denied).
    - `users` UsersPermissions
      - `create` union
        - boolean
        - object
      - `read` union
        - boolean
        - object
      - `read_simple` union
        - boolean
        - object
      - `update` union
        - boolean
        - object
      - `delete` union
        - boolean
        - object
      - `reset_usage` union
        - boolean
        - object
      - `revoke_sub` union
        - boolean
        - object
      - `set_owner` union
        - boolean
        - object
      - `activate_next_plan` union
        - boolean
        - object
    - `admins` AdminsPermissions
      - `create` union
        - boolean
        - object
      - `read` union
        - boolean
        - object
      - `read_simple` union
        - boolean
        - object
      - `update` union
        - boolean
        - object
      - `delete` union
        - boolean
        - object
      - `reset_usage` union
        - boolean
        - object
    - `nodes` NodesPermissions
      - `create` union
        - boolean
        - object
      - `read` union
        - boolean
        - object
      - `read_simple` union
        - boolean
        - object
      - `update` union
        - boolean
        - object
      - `delete` union
        - boolean
        - object
      - `reconnect` union
        - boolean
        - object
      - `update_core` union
        - boolean
        - object
      - `logs` union
        - boolean
        - object
      - `stats` union
        - boolean
        - object
    - `groups` CRUDPermissions — Standard create/read/read_simple/update/delete permissions. Used directly by: groups, templates, client_templates, cores, admin_roles. Also serves as base for resources with additional actions.
      - `create` union
        - boolean
        - object
      - `read` union
        - boolean
        - object
      - `read_simple` union
        - boolean
        - object
      - `update` union
        - boolean
        - object
      - `delete` union
        - boolean
        - object
    - `hosts` HostsPermissions
      - `create` union
        - boolean
        - object
      - `read` union
        - boolean
        - object
      - `update` union
        - boolean
        - object
    - `templates` CRUDPermissions — Standard create/read/read_simple/update/delete permissions. Used directly by: groups, templates, client_templates, cores, admin_roles. Also serves as base for resources with additional actions.
      - `create` union
        - boolean
        - object
      - `read` union
        - boolean
        - object
      - `read_simple` union
        - boolean
        - object
      - `update` union
        - boolean
        - object
      - `delete` union
        - boolean
        - object
    - `client_templates` CRUDPermissions — Standard create/read/read_simple/update/delete permissions. Used directly by: groups, templates, client_templates, cores, admin_roles. Also serves as base for resources with additional actions.
      - `create` union
        - boolean
        - object
      - `read` union
        - boolean
        - object
      - `read_simple` union
        - boolean
        - object
      - `update` union
        - boolean
        - object
      - `delete` union
        - boolean
        - object
    - `cores` CRUDPermissions — Standard create/read/read_simple/update/delete permissions. Used directly by: groups, templates, client_templates, cores, admin_roles. Also serves as base for resources with additional actions.
      - `create` union
        - boolean
        - object
      - `read` union
        - boolean
        - object
      - `read_simple` union
        - boolean
        - object
      - `update` union
        - boolean
        - object
      - `delete` union
        - boolean
        - object
    - `settings` SettingsPermissions
      - `read` union
        - boolean
        - object
      - `read_general` union
        - boolean
        - object
      - `update` union
        - boolean
        - object
    - `system` SystemPermissions
      - `read` union
        - boolean
        - object
    - `hwids` HwidsPermissions
      - `read` union
        - boolean
        - object
      - `delete` union
        - boolean
        - object
    - `admin_roles` CRUDPermissions — Standard create/read/read_simple/update/delete permissions. Used directly by: groups, templates, client_templates, cores, admin_roles. Also serves as base for resources with additional actions.
      - `create` union
        - boolean
        - object
      - `read` union
        - boolean
        - object
      - `read_simple` union
        - boolean
        - object
      - `update` union
        - boolean
        - object
      - `delete` union
        - boolean
        - object
    - `api_keys` APIKeysPermissions
      - `create` boolean, nullable
      - `read` union
        - boolean
        - object
      - `read_simple` union
        - boolean
        - object
      - `update` union
        - boolean
        - object
      - `delete` union
        - boolean
        - object
  - `limits` RoleLimits
    - `max_users` integer, nullable
    - `data_limit_min` integer, nullable
    - `data_limit_max` integer, nullable
    - `expire_min` integer, nullable
    - `expire_max` integer, nullable
    - `min_hwid_per_user` integer, nullable
    - `max_hwid_per_user` integer, nullable
    - `on_hold_timeout_min` integer, nullable
    - `on_hold_timeout_max` integer, nullable
  - `features` RoleFeatures
    - `can_use_reset_strategy` boolean
    - `can_use_next_plan` boolean
  - `access` RoleAccess
    - `require_template` boolean
    - `allowed_template_ids` integer[], nullable
    - `allowed_group_ids` integer[], nullable
  - `hwid` RoleHWIDSettings
    - `enabled` boolean
    - `forced` boolean
    - `require_hwid_for_manual_sub` boolean
    - `fallback_limit` integer, nullable
    - `min_limit` integer, nullable
    - `max_limit` integer, nullable
    - `mode` 'disabled' | 'use_global' | 'override'
  - `disabled_when_limited` boolean
  - `disconnect_users_when_limited` boolean
  - `disconnect_users_when_disabled` boolean

## Response `201`

Successful Response

- AdminRoleResponse
  - `name` string, required
  - `permissions` RolePermissions — Typed permission map. Missing resource or action = denied. Each action value is True (allowed), {"scope": N} (scoped), or None (denied).
    - `users` UsersPermissions
      - `create` union
        - boolean
        - object
      - `read` union
        - boolean
        - object
      - `read_simple` union
        - boolean
        - object
      - `update` union
        - boolean
        - object
      - `delete` union
        - boolean
        - object
      - `reset_usage` union
        - boolean
        - object
      - `revoke_sub` union
        - boolean
        - object
      - `set_owner` union
        - boolean
        - object
      - `activate_next_plan` union
        - boolean
        - object
    - `admins` AdminsPermissions
      - `create` union
        - boolean
        - object
      - `read` union
        - boolean
        - object
      - `read_simple` union
        - boolean
        - object
      - `update` union
        - boolean
        - object
      - `delete` union
        - boolean
        - object
      - `reset_usage` union
        - boolean
        - object
    - `nodes` NodesPermissions
      - `create` union
        - boolean
        - object
      - `read` union
        - boolean
        - object
      - `read_simple` union
        - boolean
        - object
      - `update` union
        - boolean
        - object
      - `delete` union
        - boolean
        - object
      - `reconnect` union
        - boolean
        - object
      - `update_core` union
        - boolean
        - object
      - `logs` union
        - boolean
        - object
      - `stats` union
        - boolean
        - object
    - `groups` CRUDPermissions — Standard create/read/read_simple/update/delete permissions. Used directly by: groups, templates, client_templates, cores, admin_roles. Also serves as base for resources with additional actions.
      - `create` union
        - boolean
        - object
      - `read` union
        - boolean
        - object
      - `read_simple` union
        - boolean
        - object
      - `update` union
        - boolean
        - object
      - `delete` union
        - boolean
        - object
    - `hosts` HostsPermissions
      - `create` union
        - boolean
        - object
      - `read` union
        - boolean
        - object
      - `update` union
        - boolean
        - object
    - `templates` CRUDPermissions — Standard create/read/read_simple/update/delete permissions. Used directly by: groups, templates, client_templates, cores, admin_roles. Also serves as base for resources with additional actions.
      - `create` union
        - boolean
        - object
      - `read` union
        - boolean
        - object
      - `read_simple` union
        - boolean
        - object
      - `update` union
        - boolean
        - object
      - `delete` union
        - boolean
        - object
    - `client_templates` CRUDPermissions — Standard create/read/read_simple/update/delete permissions. Used directly by: groups, templates, client_templates, cores, admin_roles. Also serves as base for resources with additional actions.
      - `create` union
        - boolean
        - object
      - `read` union
        - boolean
        - object
      - `read_simple` union
        - boolean
        - object
      - `update` union
        - boolean
        - object
      - `delete` union
        - boolean
        - object
    - `cores` CRUDPermissions — Standard create/read/read_simple/update/delete permissions. Used directly by: groups, templates, client_templates, cores, admin_roles. Also serves as base for resources with additional actions.
      - `create` union
        - boolean
        - object
      - `read` union
        - boolean
        - object
      - `read_simple` union
        - boolean
        - object
      - `update` union
        - boolean
        - object
      - `delete` union
        - boolean
        - object
    - `settings` SettingsPermissions
      - `read` union
        - boolean
        - object
      - `read_general` union
        - boolean
        - object
      - `update` union
        - boolean
        - object
    - `system` SystemPermissions
      - `read` union
        - boolean
        - object
    - `hwids` HwidsPermissions
      - `read` union
        - boolean
        - object
      - `delete` union
        - boolean
        - object
    - `admin_roles` CRUDPermissions — Standard create/read/read_simple/update/delete permissions. Used directly by: groups, templates, client_templates, cores, admin_roles. Also serves as base for resources with additional actions.
      - `create` union
        - boolean
        - object
      - `read` union
        - boolean
        - object
      - `read_simple` union
        - boolean
        - object
      - `update` union
        - boolean
        - object
      - `delete` union
        - boolean
        - object
    - `api_keys` APIKeysPermissions
      - `create` boolean, nullable
      - `read` union
        - boolean
        - object
      - `read_simple` union
        - boolean
        - object
      - `update` union
        - boolean
        - object
      - `delete` union
        - boolean
        - object
  - `limits` RoleLimits
    - `max_users` integer, nullable
    - `data_limit_min` integer, nullable
    - `data_limit_max` integer, nullable
    - `expire_min` integer, nullable
    - `expire_max` integer, nullable
    - `min_hwid_per_user` integer, nullable
    - `max_hwid_per_user` integer, nullable
    - `on_hold_timeout_min` integer, nullable
    - `on_hold_timeout_max` integer, nullable
  - `features` RoleFeatures
    - `can_use_reset_strategy` boolean
    - `can_use_next_plan` boolean
  - `access` RoleAccess
    - `require_template` boolean
    - `allowed_template_ids` integer[], nullable
    - `allowed_group_ids` integer[], nullable
  - `hwid` RoleHWIDSettings
    - `enabled` boolean
    - `forced` boolean
    - `require_hwid_for_manual_sub` boolean
    - `fallback_limit` integer, nullable
    - `min_limit` integer, nullable
    - `max_limit` integer, nullable
    - `mode` 'disabled' | 'use_global' | 'override'
  - `disabled_when_limited` boolean
  - `disconnect_users_when_limited` boolean
  - `disconnect_users_when_disabled` boolean
  - `id` integer, required
  - `is_owner` boolean, required
  - `created_at` string, date-time, required

## Other responses

- `401` — Unauthorized Error
- `403` — Forbidden Error
- `409` — Conflict Error
- `422` — Validation Error

---

[API](https://skmtc.dev/socialser/apis/pasarguardapi.md) · [All operations](https://skmtc.dev/socialser/apis/pasarguardapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/socialser/pasarguardapi/revisions/4b082bbcb6c3/schema)