---
title: "Create a group in an organization"
method: POST
path: "/orgs/{orgId}/groups"
tags: ["public", "Group"]
---

# Create a group in an organization

`POST /orgs/{orgId}/groups`

## Path parameters

- `orgId` string, required

## Request body

- GroupRequest — GroupRequest holds the definition of a new group.
  - `group_id` string, required — The name of the group in the IdP.
  - `idp_id` string, required — The IdP id.
  - `role` 'administrator' | 'manager' | 'member' | 'artefactContributor' | 'orgViewer', required — Roles that can be assumed by an entity on an organization.

## Response `200`

Group created with the specified Organization Role.

- GroupWithRole — GroupWithRole holds the metadata of a new group with its role in the organization.
  - `id` string, required — The id used in Humanitec to identify the group.
  - `group_id` string, required — The name of the group in the IdP
  - `idp_id` string, required — The IdP id.
  - `role` 'administrator' | 'manager' | 'member' | 'artefactContributor' | 'orgViewer', required — Roles that can be assumed by an entity on an organization.
  - `created_at` string, date-time — The time the user was first registered with Humanitec

## Other responses

- `400` — Bad request
- `403` — Server understands the request but refuses to authorize it.
- `409` — A group with the same name exists under the provided idp.

---

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