Skip to main content
A policy moves through three statuses. Only one transition, activation, changes what your organization enforces, and that transition always needs more than one person.

​
Statuses

The is_active field on a policy is deprecated. Read status instead. pending in the diagram is not a policy status. While activation is waiting for approval, the policy’s status stays draft.

​
Drafts are where all editing happens

Every write endpoint except activation works on drafts only: An enforced policy cannot be edited or deleted. To change what you enforce, create a new draft with the rules you want and activate it. The new policy becomes enforced and the old one is archived. Change an enforced policy walks through this.

​
Activation always goes through quorum

Activate policy never applies a policy immediately. It stages the draft and opens an approval request, and returns 202 Accepted:
The policy becomes enforced once the required number of quorum approvers approve the request. If the request is rejected, or reaches expires_at without enough approvals, the policy stays draft and you can activate it again. This is the two-principal invariant: no single API key, and no single person, can change what your organization enforces. A compromised key can write a permissive draft, but it cannot make that draft take effect.

​
The quorum policy

Who can approve an activation is defined by your organization’s quorum policy, a special policy with category quorum. It governs administrative operations that need multi-party approval, including policy activation.
  • Configure the quorum in the Bitnob dashboard, with at least two approvers. Until it has two, Activate policy returns 422 Unprocessable Entity.
  • Read the current quorum with Get quorum policy. It returns 404 if none is configured. The quorum policy is not included in List policies.
Set up the quorum before you go live. Without it you cannot activate any policy through the API, so your organization runs with no enforced rules.

​
Tracking an activation

There is no endpoint for the approval request itself. The approval_request_id is for matching the request in the dashboard and in webhook events. Track the outcome on the policy instead:
  • Subscribe to the policy.activated event, or
  • Poll Get policy until status is enforced. Stop polling at expires_at. If the policy is still draft, the request was rejected or expired.

​
Audit history

Get policy audit log returns every recorded action on a policy, most recent first. Each entry has the action (for example created or rule_added), the actor_id and actor_name, a timestamp, and a changes map of the fields that changed. Use it for change review and to answer auditors.

​
Approvers in rules

The quorum approves policy changes. A require_approval rule in your policy approves transactions, and names its own approvers. These can be individual users or whole roles. List approver candidates returns both. A role entry covers everyone who holds that role at the time, so approval keeps working when people join or leave. See Require approval for high-value transfers.