PUT/organizations/{organizationId}/groups/{groupId}/policy-commit
Advance a group policy and its signed directory head
Operation organizations.groups.policy.commit
Description
Commits a group's next signed principal policy, its member envelopes, the matching organization policy successor, and the container grant updates the change requires, all in one transaction. Only organization administrators may call it; a stale head returns 409. A 202 asks for the identical request to be retried after preparation, and only 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
|
groupId | path | string | required
|
Request body
application/jsonCommitOrganizationGroupPolicyRequest
A group's next policy state committed together with the organization policy successor that records its new head.
3 fields
The group's next signed state.
Successor of the reserved
Membersgroup, when the change also enrolls users in the organization.The organization's next signed state, whose directory names the group's new head.
Other fields are allowed.
Responses
200 OK
application/jsonCommitOrganizationGroupPolicyResponse
Acknowledges a group policy commit with every policy it advanced.
3 fields
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
- always
committedbooleanrequired- always
false
- always
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 |
|
| 401 | Unauthorized |
|
| 402 | Payment Required |
|
| 403 | Forbidden |
|
| 404 | Not Found |
|
| 409 | Conflict |
|
| 500 | Internal Server Error |
|
| 503 | Service Unavailable |
|
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.