---
title: "Create Group"
method: POST
path: "/api/v1/admin/groups"
tags: ["Admin APIs", "groups"]
---

# Create Group

`POST /api/v1/admin/groups`

Create a group, optionally setting its MCP period limit, MCP access and
Block role in the same request.

Runs under the router's ``groups:create`` permission even when it revokes
MCP access, unlike revoke_group_access below which requires ``groups:edit``
— a brand-new group has no members, so creating one pre-revoked takes
access away from nobody and cannot escalate anyone's privileges. No
OktaService dependency for the same reason: the revocation touches no
existing membership, so there is nothing to sync.

## Request body

- GroupCreate
  - `name` string, required
  - `description` string, nullable
  - `transaction_limit` number, nullable
  - `allocated_amount` number, nullable
  - `client_id` string, uuid, required
  - `is_default` boolean, nullable
  - `is_active` boolean, nullable
  - `meta_data` object, nullable
  - `user_ids` string[], nullable
  - `block_role` 'block_user' | 'block_admin' — Additive Block role values stored directly on ``users.block_role`` and ``groups.block_role`` (``block_role_enum`` Postgres enum). Matches the snake_case value set used elsewhere in the Block domain.
  - `mcp_period_limit` number, nullable
  - `mcp_access_revoked` boolean, nullable

## Response `200`

Successful Response

- GroupRead
  - `name` string, required
  - `description` string, nullable
  - `transaction_limit` number, nullable
  - `allocated_amount` number, nullable
  - `client_id` string, uuid, required
  - `is_default` boolean, nullable
  - `is_active` boolean, nullable
  - `meta_data` object, nullable
  - `user_ids` string[], nullable
  - `block_role` 'block_user' | 'block_admin' — Additive Block role values stored directly on ``users.block_role`` and ``groups.block_role`` (``block_role_enum`` Postgres enum). Matches the snake_case value set used elsewhere in the Block domain.
  - `id` string, uuid, required
  - `key` string, required
  - `current_consumption` number, nullable
  - `mcp_period_limit` number, nullable
  - `mcp_period_consumption` number, nullable
  - `mcp_period_reset_date` string, date-time, nullable
  - `mcp_period_next_reset_date` string, date-time, nullable
  - `mcp_period_start_date` string, date-time, nullable
  - `mcp_access_revoked` boolean, nullable
  - `mcp_access_revoked_at` string, date-time, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/carbonarc/apis/carbon-arc-client-admin-api.md) · [All operations](https://skmtc.net/carbonarc/apis/carbon-arc-client-admin-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/carbonarc/carbon-arc-client-admin-api/revisions/a8ca30023371/schema)