---
title: "Create new permission"
method: POST
path: "/api/v1/permissions"
tags: ["Permissions"]
---

# Create new permission

`POST /api/v1/permissions`

Creates a new permission that represents a specific action users can perform within the environment. Use this endpoint to define granular access controls for your RBAC system. You can provide a unique permission name following the format 'action:resource' (for example, 'read:documents', 'write:users') and an optional description explaining the permission's purpose. The permission name must be unique across the environment and follows alphanumeric naming conventions with colons and underscores. Returns the created permission object including system-generated ID and timestamps.

## Request body

- V1rolesCreatePermission
  - `description` string — Description of the permission
  - `name` string — Unique name/ID of the permission. Must be 1–64 characters using only letters, numbers, underscores (_), and colons (:).

## Response `201`

Permission created successfully. Returns the complete permission object with system-generated ID, name, description, and timestamps.

- RolesCreatePermissionResponse
  - `permission` RolesPermission
    - `create_time` string, date-time
    - `description` string
    - `id` string
    - `is_scalekit_permission` boolean — Indicates whether this permission is predefined by Scalekit
    - `name` string
    - `update_time` string, date-time

---

[API](https://skmtc.net/scalekit/apis/scalekit-api-reference.md) · [All operations](https://skmtc.net/scalekit/apis/scalekit-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/scalekit/scalekit-api-reference/versions/a40d5d4650e5/schema)