Ctrl+K

Update Policy Rules

Overview

You can update existing policy rules that are unlocked, resulting in a new version number that increases by 1. However, the ID of the policy rule remains the unchanged.

Note: To unlock a locked policy, you must contact support@bitgo.com.

Prerequisites

1. Get Touchpoint and Policy Rule

To update a policy rule, you first need to obtain the touchpoint name and policy rule ID.

Endpoint: List Policy Rules

  • cURL
1
2
3
4
5
6
7
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"

Step Result

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).

  • JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
{
  "rules": [
    {
      "uniqueId": "835c75f8-49e2-4d5b-82f0-0c8829d52a05",
      "id": "5e43e1b6-665d-4406-b59a-b9e1d2e9dfad",
      "name": "Spending limit - require approval on withdrawals of more than 2 TBTC",
      "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": "tbtc",
                "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

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 2 TBTC to more than 3 TBTC.

Endpoint: Update Policy Rule

  • cURL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
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 TBTC",
    "clauses": [
      {
        "actions": [
          {
            "name": "approvals.customer.enterpriseUser",
            "parameters": {
              "userIds": ["62ab90e06dfda30007974f0a52a12995"],
              "minRequired": "1",
              "initiatorIsAllowedToApprove": false
            }
          }
        ],
        "conditions": [
          {
            "name": "transfer.amount",
            "parameters": {
              "operator": ">",
              "amount": "300000000",
              "coin": "tbtc"
            }
          }
        ]
      }
    ],
    "filteringConditions": [
      {
        "name": "wallet.ids",
        "parameters": {
          "walletId": ["654ec786c07fe8dc0dcfe03916ec5bb0"]
        }
      }
    ]
}'

Step Result

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 you it requires approval, the policy rule remains in the PENDING_APPROVAL status until a wallet admin approves it.

  • JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
{
  "uniqueId": "a7add416-03ac-49d1-91b1-e4a6923f2713",
  "id": "5e43e1b6-665d-4406-b59a-b9e1d2e9dfad",
  "name": "Spending limit - require approval on withdrawals of more than 3 TBTC",
  "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": "tbtc"
          }
        }
      ]
    }
  ],
  "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. Approve Policy Rule (Optional)

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

3.1 Get Pending-Approval ID

To update a pending approval, you must get the pending-approval ID for the pending approval you want to respond to.

Endpoint: List Pending Approvals

  • cURL
1
2
3
4
5
6
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"

Step Result

  • JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
{
  "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 TBTC"
          }
        }
      },
      "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

Endpoint: Update Pending Approval

  • cURL
  • JavaScript
1
2
3
4
5
6
7
8
9
10
11
12
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"'"
  }'

Step Result

You approved the policy and

  • JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
{
  "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 TBTC"
      }
    }
  },
  "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"] }]
}

Next Steps

You can view your updated policy rule by calling the List policy rules endpoint.

See Also