PUT/principals/{principalType}/{principalId}/policy
Update a principal policy
Operation principals.policy.update
Description
Commits the organization's next signed principal policy and its member envelopes atomically; group policies change through the group policy commit route instead. It requires organization administrator authority, and 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 |
|---|---|---|---|
principalType | path | string | required
|
principalId | path | string | required
|
Request body
application/jsonOrganizationPrincipalPolicyRequest
The organization's next signed principal policy state, including its signed directory of group heads.
6 fields
- at most 0 items
Container mutations committed atomically with the state.
encryptedPayloadobjectrequired3 fields
cipherSuitestringrequired- always
aes-256-gcm
- always
ciphertextstringrequiredciphertextHashstringrequired
Other fields are allowed.
memberEnvelopeslist of objectrequiredThe new key epoch's key, encapsulated to each member.
4 fields
kemCipherTextstringrequiredmemberKeyFingerprintstringrequireduserIdstringrequired- lowercase UUID v4
wrappedKeystringrequired
Other fields are allowed.
projectionlist of objectrequiredThe complete membership with roles after this state.
2 fields
rolestringrequired- one of
member,admin
- one of
userIdstringrequired- lowercase UUID v4
Other fields are allowed.
stateobjectrequired20 fields
encapsulationPublicKeystringrequiredexternalAuthorityobjectrequirednullable6 fields
keyEpochintegerrequired- at least 1
keyFingerprintstringrequiredprincipalIdstringrequired- lowercase UUID v4
principalTypestringrequired- always
group
- always
stateHashstringrequiredversionintegerrequired- at least 1
Other fields are allowed.
grantCountintegerrequired- at least 0
grantRootstringrequiredkeyEpochintegerrequired- at least 1
keyFingerprintstringrequiredmemberCountintegerrequired- at least 0
memberEnvelopesRootstringrequiredmembershipModestringrequired- always
projection
- always
membershipRootstringrequiredpayloadCiphertextHashstringrequiredprevStateHashstringrequirednullableprincipalIdstringrequired- lowercase UUID v4
principalTypestringrequired- one of
group,organization
- one of
projectionRootstringrequiredsignaturestringrequiredsignedAtstringrequired- pattern
^(?:19[7-9]\d|[2-9]\d{3})-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
- pattern
signerUserIdstringrequired- lowercase UUID v4
signerUserKeyFingerprintstringrequiredversionintegerrequired- at least 1
Other fields are allowed.
Other fields are allowed.
Responses
200 OK
application/jsonPrincipalPolicyMutationResponse
A principal's current policy after a write, with acknowledgements of the container mutations committed with it.
6 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.