---
title: "Create a New Group"
method: POST
path: "/v1/tenants/{tenant_id}/realms/{realm_id}/groups"
tags: ["Groups"]
---

# Create a New Group

`POST /v1/tenants/{tenant_id}/realms/{realm_id}/groups`

## Request

- Base URL: `https://api-us.beyondidentity.com`
- URL: `https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/groups`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/beyondidentity/apis/beyond-identity-secure-access-api/docs/v1/tenants/:tenant_id/realms/:realm_id/groups/post.ts> (a function with typed inputs; its response is checked against the schema)

To create a group, send a POST request to `/v1/tenants/$TENANT_ID/realms/$REALM_ID/groups`. Values in the request body for read-only fields will be ignored.

## Path parameters

- `tenant_id` string, required
- `realm_id` string, required

## Request body

- object: Request for CreateGroup.
  - `group` Group, required: A group is a logical collection of identities. Groups are commonly used as a predicate in a policy rule.
    - `id` string: A unique identifier for a group. This is automatically generated on creation. This field is immutable and read-only. This field is unique within the realm.
    - `realm_id` string: A unique identifier for the group's realm. This is automatically set on creation. This field is immutable and read-only.
    - `tenant_id` string: A unique identifier for the group's tenant. This is automatically set on creation. This field is immutable and read-only.
    - `display_name` string: A human-readable name for the group. This name is used for display purposes.
    - `description` string: A free-form text field to describe a group.
    - `create_time` string, date-time: A time value given in ISO8601 combined date and time format that represents when the group was created. This is automatically generated on creation. This field is read-only.
    - `update_time` string, date-time: A time value given in ISO8601 combined date and time format that represents when the group was last updated. This is automatically updated when the group is updated. This field is read-only.

## Response `200`

The response will be a JSON object containing the standard attributes associated with a group.

- Group: A group is a logical collection of identities. Groups are commonly used as a predicate in a policy rule.
  - `id` string: A unique identifier for a group. This is automatically generated on creation. This field is immutable and read-only. This field is unique within the realm.
  - `realm_id` string: A unique identifier for the group's realm. This is automatically set on creation. This field is immutable and read-only.
  - `tenant_id` string: A unique identifier for the group's tenant. This is automatically set on creation. This field is immutable and read-only.
  - `display_name` string: A human-readable name for the group. This name is used for display purposes.
  - `description` string: A free-form text field to describe a group.
  - `create_time` string, date-time: A time value given in ISO8601 combined date and time format that represents when the group was created. This is automatically generated on creation. This field is read-only.
  - `update_time` string, date-time: A time value given in ISO8601 combined date and time format that represents when the group was last updated. This is automatically updated when the group is updated. This field is read-only.

## Other responses

- `400`: Bad request.
- `401`: Unauthorized.
- `403`: Forbidden.
- `404`: The resource was not found.
- `500`: Server error.

---

[API](https://skmtc.dev/beyondidentity/apis/beyond-identity-secure-access-api.md) - [All operations](https://skmtc.dev/beyondidentity/apis/beyond-identity-secure-access-api/llms.txt) - [OpenAPI document](https://skmtc.dev/beyondidentity/apis/beyond-identity-secure-access-api/revisions/42f3cac49392?raw)