---
title: "Create role"
method: POST
path: "/v2/permissions.createRole"
tags: ["permissions"]
---

# Create role

`POST /v2/permissions.createRole`

Create a new role to group related permissions for easier management. Roles enable consistent permission assignment across multiple API keys.

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

**Required Permissions**

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

## Request body

- V2PermissionsCreateRoleRequestBody
  - `name` string, required — The unique name for this role. Must be unique within your workspace and clearly indicate the role's purpose. Use descriptive names like 'admin', 'editor', or 'Billing Manager'. Examples: 'admin.billing', 'support.readonly', 'developer.api', 'Billing Manager'
  - `description` string — Provides comprehensive documentation of what this role encompasses and what access it grants. Include information about the intended use case, what permissions should be assigned, and any important considerations. This internal documentation helps team members understand role boundaries and security implications. Not visible to end users - designed for administration teams and access control audits. Consider documenting: - The role's intended purpose and scope - What types of users should receive this role - What permissions are typically associated with it - Any security considerations or limitations - Related roles that might be used together

## Response `200`

Role created successfully

- V2PermissionsCreateRoleResponseBody
  - `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` V2PermissionsCreateRoleResponseData, required
    - `roleId` string, required — The unique identifier assigned to the newly created role. Use this ID to reference the role in permission assignments, key operations, and role management calls. Always begins with 'role_' followed by a unique alphanumeric sequence. Store this ID if you need to manage, modify, or assign this role in future operations.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `409` — Conflict - A role with this 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/revisions/4bd11a7252bc/schema)