Policy
A policy defines a set of rules that control ledger behavior. Different policy types handle different concerns, and they are the primary mechanism for configuring what is allowed, required, or automated in a ledger instance.
Policies cover a wide range of behaviors:
- Access policies control who can perform actions on records
- Status policies require multiple approvals before a status change
- Labels policies validate which labels are allowed on a record
- Layout policies define record templates that pre-fill fields
- Schedule policies trigger scheduled actions like report generation
- Processing policies delegate record operations to bridges via aspects
- Authentication policies configure OAuth2 access for signers
- Custom policies are a way to store external rules in ledger
New policy types are added over time as the ledger evolves.
Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /policies | Define rules that control access, approval requirements, or automated behaviors. |
| GET | /policies | Query policies with filtering, sorting, and pagination. |
| GET | /policies/{id} | Retrieve a policy by its handle or LUID. |
| PUT | /policies/{id} | Submit a new version of a policy. |
| DELETE | /policies/{id} | Permanently remove a policy from the ledger. |
| POST | /policies/{id}/proofs | Submit a signed proof to a policy record. |
Access & History
| Method | Path | Description |
|---|---|---|
| POST | /policies/{id}/access/!check | Evaluate what actions a signer can perform on this policy. |
| GET | /policies/{id}/changes | Retrieve the change history of a policy by its handle or LUID. |
| GET | /policies/{id}/changes/{change} | Retrieve a change record for a policy by handle or LUID and change number. |
Related
- About Security Policies — how policies define access rules
- About Authorization — the access control model
- Label Policies — policies for label validation
- Processing Policies — policies that control intent processing
Get effect change GET
Returns a single change by its sequence number. The change includes a full record snapshot as it existed at that point.
Create policy POST
Policies are enforced unless their status is set to `inactive`. Use proofs to activate or deactivate a policy. The `schema` field determines the policy type: - **access** — control who can perform actions on records - **status** — define available statuses and quorum requirements for transitions - **labels** — enforce label uniqueness and assignment rules - **schedule** — trigger actions on a time-based schedule - **processing** — invoke bridges for anchor operations - **authentication** — configure OAuth 2.0 token issuance Rules within policies support filters using MongoDB-style query syntax for fine-grained matching. Broadcasts the `policy-created` signal. Use [effects](/ledger/reference/api/effect) to subscribe.