Create an organization group and advance its signed directory | API reference

Description

Creates a group with its initial signed principal policy and, in the same transaction, the organization policy successor that adds it to the signed group directory. Only organization administrators may call it. A 202 asks for the identical request to be retried after preparation; a 503 with committed: false and code principal_history_preparation_unavailable proves nothing was written.

Authentication

Requires a signed-in session: the client sends its session token as a bearer token in the Authorization header.

Parameters

Name	In	Type	Details
`organizationId`	path	string	required lowercase UUID v4

Request body

application/jsonCreateOrganizationGroupWithPolicyRequest

A new group with its first signed policy and the organization policy successor that adds it to the directory.

3 fields

groupIdstringrequired
- lowercase UUID v4
initialGroupPolicyPutPrincipalPolicyRequestrequired
organizationPolicyOrganizationPrincipalPolicyRequestrequired

Responses

200 OK

application/jsonCreateOrganizationGroupResponse

Acknowledges a new group and the organization policy that lists it.

2 fields

groupOrganizationGroupSummaryResponserequired
organizationPolicyPrincipalPolicyMutationResponserequired

Other fields are allowed.

202 The attempted operation rolled back. Retry the identical request to continue verification preparation.

application/jsonPrincipalHistoryPreparationResponse

A 202: the operation rolled back while the server prepares principal history. Retry the identical request.

3 fields

codestringrequired
- always principal_history_preparation_pending
committedbooleanrequired
- always false
progressTokenstringrequired
- exactly 64 characters
- lowercase hexadecimal
Changes when preparation advances; clients stop after three identical tokens in a row.

Other responses

Status	Meaning	Body
400	Bad Request	`application/json`ErrorResponse
401	Unauthorized	`application/json`SessionFailureResponse
402	Payment Required	`application/json`PaymentRequiredErrorResponse
403	Forbidden	`application/json`ErrorResponse
404	Not Found	`application/json`ErrorResponse
409	Conflict	`application/json`ErrorResponse
500	Internal Server Error	`application/json`ErrorResponse
503	Service Unavailable	`application/json`PrincipalHistoryPreparationFailureResponse

Additional rules

The server also enforces these rules, which the schema above cannot express.

A container response keyring is null exactly for container key epoch 1.
A 503 with code principal_history_preparation_unavailable requires committed:false; other 503 responses do not guarantee rollback.