--- title: "POST /v1/groups" method: POST path: "/v1/groups" tags: ["groups"] --- # POST /v1/groups `POST /v1/groups` Creates a Group. ## Query parameters - `initialGroupConfig` 'INITIAL_GROUP_CONFIG_UNSPECIFIED' | 'WITH_INITIAL_OWNER' | 'EMPTY' ## Request body - Group — A group within the Cloud Identity Groups API. A `Group` is a collection of entities, where each entity is either a user, another group, or a service account. - `groupKey` EntityKey — A unique identifier for an entity in the Cloud Identity Groups API. An entity can represent either a group with an optional `namespace` or a user without a `namespace`. The combination of `id` and `namespace` must be unique; however, the same `id` can be used with different `namespace`s. - `id` string — The ID of the entity. For Google-managed entities, the `id` should be the email address of an existing group or user. Email addresses need to adhere to [name guidelines for users and groups](https://support.google.com/a/answer/9193374). For external-identity-mapped entities, the `id` must be a string conforming to the Identity Source's requirements. Must be unique within a `namespace`. - `namespace` string — The namespace in which the entity exists. If not specified, the `EntityKey` represents a Google-managed entity such as a Google user or a Google Group. If specified, the `EntityKey` represents an external-identity-mapped group. The namespace must correspond to an identity source created in Admin Console and must be in the form of `identitysources/{identity_source}`. - `description` string — An extended description to help users determine the purpose of a `Group`. Must not be longer than 4,096 characters. - `updateTime` string, google-datetime — Output only. The time when the `Group` was last updated. - `parent` string — Required. Immutable. The resource name of the entity under which this `Group` resides in the Cloud Identity resource hierarchy. Must be of the form `identitysources/{identity_source}` for external [identity-mapped groups](https://support.google.com/a/answer/9039510) or `customers/{customer_id}` for Google Groups. The `customer_id` must begin with "C" (for example, 'C046psxkn'). [Find your customer ID.] (https://support.google.com/cloudidentity/answer/10070793) - `createTime` string, google-datetime — Output only. The time when the `Group` was created. - `name` string — Output only. The [resource name](https://cloud.google.com/apis/design/resource_names) of the `Group`. Shall be of the form `groups/{group}`. - `additionalGroupKeys` EntityKey[] — Output only. Additional group keys associated with the Group. - `id` string — The ID of the entity. For Google-managed entities, the `id` should be the email address of an existing group or user. Email addresses need to adhere to [name guidelines for users and groups](https://support.google.com/a/answer/9193374). For external-identity-mapped entities, the `id` must be a string conforming to the Identity Source's requirements. Must be unique within a `namespace`. - `namespace` string — The namespace in which the entity exists. If not specified, the `EntityKey` represents a Google-managed entity such as a Google user or a Google Group. If specified, the `EntityKey` represents an external-identity-mapped group. The namespace must correspond to an identity source created in Admin Console and must be in the form of `identitysources/{identity_source}`. - `displayName` string — The display name of the `Group`. - `labels` object — Required. One or more label entries that apply to the Group. Labels contain a key with an empty value. Google Groups are the default type of group and have a label with a key of `cloudidentity.googleapis.com/groups.discussion_forum` and an empty value. Existing Google Groups can have an additional label with a key of `cloudidentity.googleapis.com/groups.security` and an empty value added to them. **This is an immutable change and the security label cannot be removed once added.** Dynamic groups have a label with a key of `cloudidentity.googleapis.com/groups.dynamic`. Identity-mapped groups for Cloud Search have a label with a key of `system/groups/external` and an empty value. Google Groups can be [locked](https://support.google.com/a?p=locked-groups). To lock a group, add a label with a key of `cloudidentity.googleapis.com/groups.locked` and an empty value. Doing so locks the group. To unlock the group, remove this label. - `dynamicGroupMetadata` DynamicGroupMetadata — Dynamic group metadata like queries and status. - `status` DynamicGroupStatus — The current status of a dynamic group along with timestamp. - `status` 'STATUS_UNSPECIFIED' | 'UP_TO_DATE' | 'UPDATING_MEMBERSHIPS' | 'INVALID_QUERY' — Status of the dynamic group. - `statusTime` string, google-datetime — The latest time at which the dynamic group is guaranteed to be in the given status. If status is `UP_TO_DATE`, the latest time at which the dynamic group was confirmed to be up-to-date. If status is `UPDATING_MEMBERSHIPS`, the time at which dynamic group was created. - `queries` DynamicGroupQuery[] — Memberships will be the union of all queries. Only one entry with USER resource is currently supported. Customers can create up to 500 dynamic groups. - `resourceType` 'RESOURCE_TYPE_UNSPECIFIED' | 'USER' — Resource type for the Dynamic Group Query - `query` string — Query that determines the memberships of the dynamic group. Examples: All users with at least one `organizations.department` of engineering. `user.organizations.exists(org, org.department=='engineering')` All users with at least one location that has `area` of `foo` and `building_id` of `bar`. `user.locations.exists(loc, loc.area=='foo' && loc.building_id=='bar')` All users with any variation of the name John Doe (case-insensitive queries add `equalsIgnoreCase()` to the value being queried). `user.name.value.equalsIgnoreCase('jOhn DoE')` ## Response `200` Successful response --- [API](https://skmtc.net/google/apis/cloudidentity.md) · [All operations](https://skmtc.net/google/apis/cloudidentity/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/google/cloudidentity/versions/179b4eeed5a2/schema)