GET/principals/{principalType}/{principalId}/policy
Get a principal policy bundle
Operation principals.policy.get
Description
Returns a page of a group or organization's signed principal policy chain with its current member envelopes, so the client can verify the chain and a member can unwrap the principal's key; a conditional read that names the still-current head gets a short unchanged reply instead. It is served only to callers who depend on it: active roster members, members of the principal, or holders of a grant whose path cites it. A 202 asks the client to retry the identical request after policy history is prepared.
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
|
afterVersion | query | integer | optional
|
stateHash | query | string | optional
|
ifVersion | query | integer | optional
|
ifStateHash | query | string | optional
|
Responses
200 OK
application/jsonPrincipalPolicyReadResponse
A principal policy page, or the short unchanged reply to a conditional read.
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 |
|
| 403 | Forbidden |
|
| 409 | Conflict |
|
| 500 | Internal Server Error |
|
| 503 | Service Unavailable |
|