Update Policy Rules

Update existing unlocked policy rules for your enterprise. See the Guide.

To update a policy rule, you first need to obtain the touchpoint name and policy rule ID. You return all the policy rules for your enterprise. Identify the policy rule you want to update and make note of the touchpoint name (name field within the filteringConditions array) and the policy rule ID (the id field).

Prerequisites:
- Get Started
- Create Policy Rules
API Reference
Use the touchpoint name and policy rule ID you obtained in the prior step to update the policy rule. The following example updates a policy rule from requiring approvals on withdrawals of more than two TBTC4 to more than 3 TBTC4.

The updated policy rule enters a PENDING_APPROVAL status. If the updated policy rule doesn't require approval, it automatically updates to ACTIVE status within a short period of time. If it requires approval, the policy rule remains in the PENDING_APPROVAL status until a wallet admin approves it.

API Reference
If you configure an approval requirement for policy rules, you can't approve your own policy-rule changes -- another admin must approve them.

First, get the pending-approval ID by listing pending approvals (step 3.1). Then, use the pending-approval ID to approve the pending approval (step 3.2).

API Reference

// 1. Get Touchpoint and Policy Rule
export ENTERPRISE_ID="<YOUR_ENTERPRISE_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"

curl -X GET \
  "https://app.bitgo-test.com/api/policy/v1/enterprises/$ENTERPRISE_ID/rules" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
// 2. Update Policy Rule
export ENTERPRISE_ID="<YOUR_ENTERPRISE_ID>"
export TOUCHPOINT="<TOUCHPOINT_NAME>"
export ID="<POLICY_RULE_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"

curl -X PUT \
  "https://app.bitgo-test.com/api/policy/v1/enterprises/$ENTERPRISE_ID/touchpoints/$TOUCHPOINT/rules/$ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "name": "Spending limit - require approval on withdrawals of more than 3 TBTC4",
    "clauses": [
      {
        "actions": [
          {
            "name": "approvals.customer.enterpriseUser",
            "parameters": {
              "userIds": ["62ab90e06dfda30007974f0a52a12995"],
              "minRequired": "1",
              "initiatorIsAllowedToApprove": false
            }
          }
        ],
        "conditions": [
          {
            "name": "transfer.amount",
            "parameters": {
              "operator": ">",
              "amount": "300000000",
              "coin": "tbtc4"
            }
          }
        ]
      }
    ],
    "filteringConditions": [
      {
        "name": "wallet.ids",
        "parameters": {
          "walletId": ["654ec786c07fe8dc0dcfe03916ec5bb0"]
        }
      }
    ]
}'
// 3.1 Get Pending-Approval ID
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"

curl -X GET \
  https://app.bitgo-test.com/api/v2/pendingApprovals \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

// 3.2 Approve Pending Approval
export APPROVAL_ID="<APPROVAL_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export OTP="<YOUR_OTP>"

curl -X PUT \
  https://app.bitgo-test.com/api/v2/pendingApprovals/$APPROVAL_ID \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "state": "approved",
    "otp": "'"$OTP"'"
  }'

// 1. Get Touchpoint and Policy Rule
// Use the REST API for this step (see cURL tab)
// 2. Update Policy Rule
// Use the REST API for this step (see cURL tab)
// 3.1 Get Pending-Approval ID
// Use the REST API for this step (see cURL tab)

// 3.2 Approve Pending Approval
const baseCoin = this.bitgoSDK.coin(initialPendingApproval.coin);
const pendingApproval = await baseCoin.pendingApprovals().get({ id: initialPendingApproval.id });
const result = await pendingApproval.approve(params);

Response

// 1. Get Touchpoint and Policy Rule Response
{
  "rules": [
    {
      "uniqueId": "835c75f8-49e2-4d5b-82f0-0c8829d52a05",
      "id": "5e43e1b6-665d-4406-b59a-b9e1d2e9dfad",
      "name": "Spending limit - require approval on withdrawals of more than two TBTC4",
      "status": "ACTIVE",
      "version": 1,
      "adminOnly": false,
      "touchpointId": "166082ab-9268-4369-996a-b4ac63f6f634",
      "scopeId": "c8234a0f-7722-44d7-bedc-bfded7bd24a7",
      "touchpointLabel": "Withdrawal",
      "scopeLabel": "Wallet",
      "clauses": [
        {
          "actions": [
            {
              "name": "approvals.customer.enterpriseUser",
              "parameters": {
                "userIds": ["62ab90e06dfda30007974f0a52a12995"],
                "minRequired": "1",
                "initiatorIsAllowedToApprove": false
              }
            }
          ],
          "conditions": [
            {
              "name": "transfer.amount",
              "parameters": {
                "coin": "tbtc4",
                "amount": "200000000",
                "operator": ">"
              }
            }
          ]
        }
      ],
      "filteringConditions": [
        {
          "name": "wallet.ids",
          "parameters": { "walletId": ["654ec786c07fe8dc0dcfe03916ec5bb0"] }
        }
      ],
      "locked": false,
      "lockType": "LOCK_AFTER_DATE",
      "lockDate": "2024-04-14T18:52:07.955224Z",
      "createdDate": "2024-04-12T18:52:07.955235Z",
      "modifiedDate": "2024-04-12T18:58:30.279159Z",
      "enterpriseId": "62c5ae8174ac860007aff138a2d74df7",
      "createdBy": "62ab90e06dfda30007974f0a52a12995",
      "modifiedBy": "62ab90e06dfda30007974f0a52a12995",
      "evaluationId": "57cd4e69-8038-4568-8124-55ca80ff94c1"
    }
  ],
  "nextBatchPrevId": "2"
}

// 2. Update Policy Rule Response
{
  "uniqueId": "a7add416-03ac-49d1-91b1-e4a6923f2713",
  "id": "5e43e1b6-665d-4406-b59a-b9e1d2e9dfad",
  "name": "Spending limit - require approval on withdrawals of more than 3 TBTC4",
  "status": "PENDING_APPROVAL",
  "adminOnly": false,
  "touchpointId": "166082ab-9268-4369-996a-b4ac63f6f634",
  "scopeId": "c8234a0f-7722-44d7-bedc-bfded7bd24a7",
  "touchpointLabel": "Withdrawal",
  "scopeLabel": "Wallet",
  "clauses": [
    {
      "actions": [
        {
          "name": "approvals.customer.enterpriseUser",
          "parameters": {
            "userIds": ["62ab90e06dfda30007974f0a52a12995"],
            "minRequired": "1",
            "initiatorIsAllowedToApprove": false
          }
        }
      ],
      "conditions": [
        {
          "name": "transfer.amount",
          "parameters": {
            "operator": ">",
            "amount": "300000000",
            "coin": "tbtc4"
          }
        }
      ]
    }
  ],
  "filteringConditions": [
    {
      "name": "wallet.ids",
      "parameters": { "walletId": ["654ec786c07fe8dc0dcfe03916ec5bb0"] }
    }
  ],
  "locked": false,
  "lockType": "LOCK_AFTER_DATE",
  "lockDate": "2024-04-14T18:52:07.955224Z",
  "createdDate": "2024-04-12T19:06:41.185719Z",
  "modifiedDate": "2024-04-12T19:06:41.296314Z",
  "enterpriseId": "62c5ae8174ac860007aff138a2d74df7",
  "createdBy": "62ab90e06dfda30007974f0a52a12995",
  "modifiedBy": "627ff9325a5c1b0007c05a40d15e1522",
  "evaluationId": "75ba4f44-6560-46c5-9e3f-fc44ae7b8064"
}

// 3.1 Get Pending-Approval ID Response
{
  "pendingApprovals": [
    {
      "id": "66198641c052b0d78cda476c8b97a3ac",
      "wallet": "654ec786c07fe8dc0dcfe03916ec5bb0",
      "enterprise": "62c5ae8174ac860007aff138a2d74df7",
      "bitgoOrg": "BitGo Trust",
      "creator": "627ff9325a5c1b0007c05a40d15e1522",
      "createDate": "2024-04-12T19:06:41.331Z",
      "info": {
        "type": "genericRequest",
        "genericRequest": {
          "description": "Request to update policy rule {policyRuleId}",
          "anchors": [
            {
              "key": "policyRuleId",
              "value": "835c75f8-49e2-4d5b-82f0-0c8829d52a05",
              "anchorType": "policyRuleId"
            }
          ],
          "currentId": "835c75f8-49e2-4d5b-82f0-0c8829d52a05",
          "proposedId": "a7add416-03ac-49d1-91b1-e4a6923f2713",
          "resourceType": "policyRule",
          "changeType": "update",
          "metadata": {
            "sharedId": "5e43e1b6-665d-4406-b59a-b9e1d2e9dfad",
            "policyRuleName": "Spending limit - require approval on withdrawals of more than 3 TBTC4"
          }
        }
      },
      "approvers": [
        "62ab90e06dfda30007974f0a52a12995",
        "621d08a634ad8a0007fcddffd7c429cc"
      ],
      "state": "pending",
      "scope": "wallet",
      "userIds": [
        "62ab90e06dfda30007974f0a52a12995",
        "621d08a634ad8a0007fcddffd7c429cc",
        "627ff9325a5c1b0007c05a40d15e1522"
      ],
      "approvalsRequired": 1,
      "singleRunResults": [],
      "resolvers": [],
      "policyEvaluationId": "75ba4f44-6560-46c5-9e3f-fc44ae7b8064",
      "actions": [
        {
          "id": "f136bf6e-91c1-4d1b-a205-6636fbf0a527",
          "status": "PENDING",
          "name": "approvals.customer.walletAdmin",
          "parameters": { "userIds": [] },
          "resolvers": [],
          "approvers": [
            "62ab90e06dfda30007974f0a52a12995",
            "621d08a634ad8a0007fcddffd7c429cc"
          ]
        }
      ],
      "resolutionOrder": [
        { "actions": ["f136bf6e-91c1-4d1b-a205-6636fbf0a527"] }
      ]
    }
  ]
}

// 3.2 Approve Pending Approval Response
{
  "id": "66198641c052b0d78cda476c8b97a3ac",
  "wallet": "654ec786c07fe8dc0dcfe03916ec5bb0",
  "enterprise": "62c5ae8174ac860007aff138a2d74df7",
  "bitgoOrg": "BitGo Trust",
  "creator": "627ff9325a5c1b0007c05a40d15e1522",
  "createDate": "2024-04-12T19:06:41.331Z",
  "approvedDate": "2024-04-12T19:09:15.275Z",
  "info": {
    "type": "genericRequest",
    "genericRequest": {
      "description": "Request to update policy rule {policyRuleId}",
      "anchors": [
        {
          "key": "policyRuleId",
          "value": "835c75f8-49e2-4d5b-82f0-0c8829d52a05",
          "anchorType": "policyRuleId"
        }
      ],
      "currentId": "835c75f8-49e2-4d5b-82f0-0c8829d52a05",
      "proposedId": "a7add416-03ac-49d1-91b1-e4a6923f2713",
      "resourceType": "policyRule",
      "changeType": "update",
      "metadata": {
        "sharedId": "5e43e1b6-665d-4406-b59a-b9e1d2e9dfad",
        "policyRuleName": "Spending limit - require approval on withdrawals of more than 3 TBTC4"
      }
    }
  },
  "approvers": [],
  "state": "approved",
  "scope": "wallet",
  "userIds": [
    "62ab90e06dfda30007974f0a52a12995",
    "621d08a634ad8a0007fcddffd7c429cc",
    "627ff9325a5c1b0007c05a40d15e1522"
  ],
  "approvalsRequired": 1,
  "singleRunResults": [],
  "resolvers": [
    {
      "user": "62ab90e06dfda30007974f0a52a12995",
      "date": "2024-04-12T19:09:15.120Z",
      "resolutionType": "pending",
      "resolutionAction": "approve"
    }
  ],
  "policyEvaluationId": "75ba4f44-6560-46c5-9e3f-fc44ae7b8064",
  "actions": [
    {
      "id": "f136bf6e-91c1-4d1b-a205-6636fbf0a527",
      "status": "COMPLETE",
      "name": "approvals.customer.walletAdmin",
      "parameters": { "userIds": [] },
      "resolvers": [
        {
          "user": "62ab90e06dfda30007974f0a52a12995",
          "date": "2024-04-12T19:09:15.120Z",
          "resolutionType": "pending",
          "resolutionAction": "approve"
        }
      ],
      "approvers": ["621d08a634ad8a0007fcddffd7c429cc"]
    }
  ],
  "resolutionOrder": [{ "actions": ["f136bf6e-91c1-4d1b-a205-6636fbf0a527"] }]
}