---
title: "Create a custom role with an exact capability set"
method: POST
path: "/v1/roles"
tags: ["roles"]
---

# Create a custom role with an exact capability set

`POST /v1/roles`

## Request

- Base URL: `https://api.typenode.ai`
- URL: `https://api.typenode.ai/v1/roles`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string, uuid, required

## Request body

- CreateRole
  - `capabilities` CapabilityEntryInput[]
    - `capability_token` string, required
    - `environment_id` string, uuid, nullable
    - `expires_at` string, date-time, nullable
    - `resource_id` string, uuid, nullable
    - `resource_type` string, nullable
    - `scope_kind` 'workspace' | 'self' | 'resource' | 'parent' | 'parent_self', required
  - `description` string, nullable
  - `name` string, required

## Response `201`

The created role, with its capability set.

- RoleDetail
  - `assignee_count` integer, required
  - `capabilities` RoleCapabilityEntry[], required
    - `all_capabilities` boolean, required
    - `capability_token` string, nullable, required
    - `environment_id` string, uuid, nullable, required
    - `expires_at` string, date-time, nullable, required
    - `resource_id` string, uuid, nullable, required
    - `resource_type` string, nullable, required
    - `scope_kind` 'workspace' | 'self' | 'resource' | 'parent' | 'parent_self', required
  - `created_at` string, date-time, required
  - `description` string, nullable, required
  - `id` string, uuid, required
  - `name` string, required
  - `template_key` 'owner' | 'builder' | 'operator' | 'viewer' | 'everyone', nullable, required
  - `version` integer, required

## Other responses

- `400`: Invalid request body, missing Idempotency-Key, or an unknown capability_token.
- `401`: Authentication required.
- `403`: role.write is required.
- `409`: The idempotency key conflicts, the role name already exists, or the tenant role cap is reached.
- `default`: An error occurred (RFC 9457 problem+json).

---

[API](https://skmtc.dev/typenode/apis/typenode-management-api.md) · [All operations](https://skmtc.dev/typenode/apis/typenode-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/typenode/apis/typenode-management-api/revisions/9b943024aa98?raw)