---
title: "Create a custom role"
method: POST
path: "/teams/{team_id}/create_custom_role"
tags: ["Custom Roles"]
---

# Create a custom role

`POST /teams/{team_id}/create_custom_role`

Creates a new custom role for the team with the specified name,
description, and permission statements.

## Path parameters

- `team_id` integer, required

## Request body

- CreateCustomRoleArgs
  - `name` string, required
  - `description` string, nullable
  - `statements` RoleStatement[], required
    - `effect` 'allow' | 'deny', required — Whether a rule grants or revokes access.
    - `actions` union, required
      - '*'
      - RoleStatementAction[]
    - `resource` string, required — Resource path like `project:*`, `project:slug=my-app`, or `project:*:deployment:type=prod`.

## Response `201`

- CustomRoleResponse
  - `id` integer, required
  - `teamId` integer, required
  - `name` string, required
  - `description` string, nullable
  - `statements` RoleStatement[], required
    - `effect` 'allow' | 'deny', required — Whether a rule grants or revokes access.
    - `actions` union, required
      - '*'
      - RoleStatementAction[]
    - `resource` string, required — Resource path like `project:*`, `project:slug=my-app`, or `project:*:deployment:type=prod`.
  - `creator` integer
  - `createTime` integer, required

## Changes

- **2026-08-27** `005e83eb28f0` — 6 warning, 6 info
  - added the new `deployment:aiGateway:use` enum value to the `statements/items/actions/oneOf[subschema #2]/items/` response property for the response status `201`
  - added the new `directorySync:deleteGroupMapping` enum value to the `statements/items/actions/oneOf[subschema #2]/items/` response property for the response status `201`
  - added the new `directorySync:disable` enum value to the `statements/items/actions/oneOf[subschema #2]/items/` response property for the response status `201`
  - added the new `directorySync:enable` enum value to the `statements/items/actions/oneOf[subschema #2]/items/` response property for the response status `201`
  - …8 more
- **2026-08-25** `d6dde3ef057c` — 1 info
  - the endpoint scheme security `OAuth Team Token` was removed from the API
- **2026-07-26** `cfe35d359fba` — 1 warning, 1 info
  - added the new `deployment:usage:view` enum value to the `statements/items/actions/oneOf[subschema #2]/items/` response property for the response status `201`
  - added the new `deployment:usage:view` enum value to the request property `statements/items/actions/oneOf[subschema #2]/items/`

[Change history](https://skmtc.dev/convex/apis/convex-management-api/changes/teams/:team_id/create_custom_role/post.md)

---

[API](https://skmtc.dev/convex/apis/convex-management-api.md) · [All operations](https://skmtc.dev/convex/apis/convex-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/convex/convex-management-api/revisions/8107cc743e0b/schema)