---
title: "Create permission"
method: POST
path: "/v2/permissions.createPermission"
tags: ["permissions"]
---

# Create permission

`POST /v2/permissions.createPermission`

Create a new permission to define specific actions or capabilities in your RBAC system. Permissions can be assigned directly to API keys or included in roles.

Use hierarchical naming patterns like `documents.read`, `admin.users.delete`, or `billing.invoices.create` for clear organization.

**Important:** Permission names must be unique within the workspace. Once created, permissions are immediately available for assignment.

**Required Permissions**

Your root key must have the following permission:
- `rbac.*.create_permission`

## Request body

- V2PermissionsCreatePermissionRequestBody
  - `name` string, required — Creates a permission with this human-readable name that describes its purpose. Names must be unique within your workspace to prevent conflicts during assignment. Use clear, semantic names that developers can easily understand when building authorization logic. Consider using hierarchical naming conventions like 'resource.action' for better organization. Examples: 'users.read', 'billing.write', 'analytics.view', 'admin.manage'
  - `slug` string, required — Creates a URL-safe identifier for this permission that can be used in APIs and integrations. Must start with a letter and contain only letters, numbers, periods, underscores, and hyphens. Slugs are often used in REST endpoints, configuration files, and external integrations. Should closely match the name but in a format suitable for technical usage. Must be unique within your workspace to ensure reliable permission lookups. Keep slugs concise but descriptive for better developer experience.
  - `description` string — Provides detailed documentation of what this permission grants access to. Include information about affected resources, allowed actions, and any important limitations. This internal documentation helps team members understand permission scope and security implications. Not visible to end users - designed for development teams and security audits. Consider documenting: - What resources can be accessed - What operations are permitted - Any conditions or limitations - Related permissions that might be needed

## Response `200`

Permission created successfully

- V2PermissionsCreatePermissionResponseBody
  - `meta` Meta, required — Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required — A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` V2PermissionsCreatePermissionResponseData, required
    - `permissionId` string, required — The unique identifier assigned to the newly created permission. Use this ID to reference the permission in role assignments, key operations, and other API calls. Always begins with 'perm_' followed by a unique alphanumeric sequence. Store this ID if you need to manage or reference this permission in future operations.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `409` — Conflict - permission with that name already exists
- `429` — Too Many Requests
- `500` — Internal Server Error

---

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