Crypto-as-a-Service: Create Policy Rules

Create policy rules to secure sensitive operations. See the Guide.

Before you can create a policy rule, you must get the scope ID for the scope you want to create the rule for. Scopes are entities or sets of entities that you can control using a policy rule.

API Reference
Using the scope ID returned in the prior step, list all the available touchpoints for the given scope. Save the touchpoint name that you want to create a policy rule for.

API Reference
Using the touchpoint name returned in the prior step, create a policy rule for the given touchpoint. The example creates a policy rule that requires approval from a specific user for withdrawals of more than $100 from a specific wallet. The new policy rule enters a PENDING_APPROVAL status.

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. This step has two substeps:

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.

API Reference

Approve Pending Approval

Approve the pending policy rule using the approval ID from the previous substep.

API Reference

// 1. Get Scope ID
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/scopes" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
// 2. Get Touchpoint Name
export ENTERPRISE_ID="<YOUR_ENTERPRISE_ID>"
export SCOPE_ID="<SCOPE_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"

curl -X GET \
  "https://app.bitgo-test.com/api/policy/v1/enterprises/$ENTERPRISE_ID/scopes/$SCOPE_ID/touchpoints" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
// 3. Create Policy Rule
export ENTERPRISE_ID="<YOUR_ENTERPRISE_ID>"
export TOUCHPOINT="<TOUCHPOINT_NAME>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export USER_ID="<APPROVER_USER_ID>"
export WALLET_ID="<WALLET_ID>"

curl -X POST \
  "https://app.bitgo-test.com/api/policy/v1/enterprises/$ENTERPRISE_ID/touchpoints/$TOUCHPOINT/rules" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "name": "Spending limit - require approval on withdrawals of more than 100 USD",
    "adminOnly": false,
    "clauses": [
        {
            "conditions": [
                {
                    "name": "transfer.amount",
                    "parameters": {
                        "operator": ">",
                        "amount": "100",
                        "coin": "usd"
                    }
                }
            ],
            "actions": [
                {
                    "name": "approvals.customer.enterpriseUser",
                    "parameters": {
                        "userIds": [
                            "'"$USER_ID"'"
                        ],
                        "minRequired": "1",
                        "initiatorIsAllowedToApprove": false
                    }
                }
            ]
        }
    ],
    "filteringConditions": [
        {
            "name": "wallet.ids",
            "parameters": {
                "walletId": [
                    "'"$WALLET_ID"'"
                ]
            }
        }
    ]
}'
// 4. Approve Policy Rule (Optional)
// 4.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"

// 4.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 Scope ID
// Use the REST API for this step (see cURL tab)
// 2. Get Touchpoint Name
// Use the REST API for this step (see cURL tab)
// 3. Create Policy Rule
// Use the REST API for this step (see cURL tab)
// 4. Approve Policy Rule (Optional)
// 4.1 Get Pending-Approval ID
// Use the REST API for this step (see cURL tab)

// 4.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 Scope ID Response
{
  "scopes": [
    {
      "id": "c8234a0f-7722-44d7-bedc-bfded7bd24a7",
      "name": "wallet.segregated",
      "label": "Wallet",
      "description": "A BitGo Wallet",
      "conditions": [
        {
          "name": "wallet.type",
          "label": "Wallet Type",
          "description": "Allows creating a Condition based on the Wallet Type",
          "status": "ACTIVE",
          "parameters": [
            {
              "name": "walletType",
              "label": "Type",
              "description": "The Wallet Type",
              "type": "ENUMERATED",
              "required": "ALWAYS",
              "allowMultiple": true,
              "values": [
                {
                  "value": "custodial",
                  "label": "Custody Wallet",
                  "description": "A custody wallet"
                },
                {
                  "value": "hot",
                  "label": "Hot Wallet",
                  "description": "A hot wallet"
                },
                {
                  "value": "cold",
                  "label": "BitGo Offline Vault wallet",
                  "description": "A cold wallet"
                },
                {
                  "value": "trading",
                  "label": "Go Account",
                  "description": "A trading wallet"
                }
              ]
            }
          ]
        },
        {
          "name": "wallet.ids",
          "label": "Single Wallet",
          "description": "Allows creating a Condition based on the Wallet Id",
          "status": "ACTIVE",
          "parameters": [
            {
              "name": "walletId",
              "label": "Wallet Id",
              "description": "The Wallet Ids",
              "type": "BITGO_WALLET_ID",
              "required": "ALWAYS",
              "allowMultiple": false,
              "values": []
            }
          ]
        },
        {
          "name": "wallet.all",
          "label": "All wallets in my enterprise",
          "description": "Applies to All Wallets",
          "status": "ACTIVE",
          "parameters": []
        }
      ]
    }
  ]
}

// 2. Get Touchpoint Name Response
{
  "touchpoints": [
    {
      "id": "166082ab-9268-4369-996a-b4ac63f6f634",
      "name": "wallet.segregated.transfer",
      "status": "ACTIVE",
      "label": "Withdrawal",
      "description": "Withdrawal from a BitGo Wallet",
      "adminOnly": false
    },
    {
      "id": "0e0c1126-daf3-4b79-a05c-094ebd30007d",
      "name": "goaccount.settlement.signed",
      "status": "ACTIVE",
      "label": "Settlement Initiated",
      "description": "When a settlement is initiated from a BitGo Go Account Wallet",
      "adminOnly": false
    },
    {
      "id": "8c0a1a3f-7f20-4ff1-aa8a-ac28a217f3f3",
      "name": "goaccount.settlement.countersigned",
      "status": "ACTIVE",
      "label": "Settlement Approved",
      "description": "When a settlement is accepted by a user on a BitGo Go Account Wallet",
      "adminOnly": false
    }
  ],
  "page": 1,
  "totalPages": 1,
  "totalElements": 3
}

// 3. Create Policy Rule Response
{
  "uniqueId": "835c75f8-49e2-4d5b-82f0-0c8829d52a05",
  "id": "5e43e1b6-665d-4406-b59a-b9e1d2e9dfad",
  "name": "Spending limit - require approval on withdrawals of more than 100 USD",
  "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": "100",
            "coin": "usd"
          }
        }
      ]
    }
  ],
  "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:52:08.041738Z",
  "enterpriseId": "62c5ae8174ac860007aff138a2d74df7",
  "createdBy": "62ab90e06dfda30007974f0a52a12995",
  "modifiedBy": "62ab90e06dfda30007974f0a52a12995",
  "evaluationId": "57cd4e69-8038-4568-8124-55ca80ff94c1"
}

// 4. Approve Policy Rule (Optional)
// 4.1 Get Pending-Approval ID Response
{
  "pendingApprovals": [
    {
      "id": "661982d8e1ee8192595fed2145490e13",
      "wallet": "654ec786c07fe8dc0dcfe03916ec5bb0",
      "enterprise": "62c5ae8174ac860007aff138a2d74df7",
      "bitgoOrg": "BitGo Trust",
      "creator": "62ab90e06dfda30007974f0a52a12995",
      "createDate": "2024-04-12T18:52:08.072Z",
      "info": {
        "type": "genericRequest",
        "genericRequest": {
          "description": "Request to create policy rule {policyRuleId}",
          "anchors": [
            {
              "key": "policyRuleId",
              "value": "835c75f8-49e2-4d5b-82f0-0c8829d52a05",
              "anchorType": "policyRuleId"
            }
          ],
          "proposedId": "835c75f8-49e2-4d5b-82f0-0c8829d52a05",
          "resourceType": "policyRule",
          "changeType": "create",
          "metadata": {
            "sharedId": "5e43e1b6-665d-4406-b59a-b9e1d2e9dfad",
            "policyRuleName": "Spending limit - require approval on withdrawals of more than 100 USD"
          }
        }
      },
      "approvers": [
        "621d08a634ad8a0007fcddffd7c429cc",
        "627ff9325a5c1b0007c05a40d15e1522"
      ],
      "state": "pending",
      "scope": "wallet",
      "userIds": [
        "62ab90e06dfda30007974f0a52a12995",
        "621d08a634ad8a0007fcddffd7c429cc",
        "627ff9325a5c1b0007c05a40d15e1522"
      ],
      "approvalsRequired": 1,
      "singleRunResults": [],
      "resolvers": [],
      "policyEvaluationId": "57cd4e69-8038-4568-8124-55ca80ff94c1",
      "actions": [
        {
          "id": "65a52063-df3b-4362-bfc1-68d4e8b2cc6f",
          "status": "PENDING",
          "name": "approvals.customer.walletAdmin",
          "parameters": { "userIds": [] },
          "resolvers": [],
          "approvers": [
            "621d08a634ad8a0007fcddffd7c429cc",
            "627ff9325a5c1b0007c05a40d15e1522"
          ]
        }
      ],
      "resolutionOrder": [
        { "actions": ["65a52063-df3b-4362-bfc1-68d4e8b2cc6f"] }
      ]
    }
  ]
}

// 4.2 Approve Pending Approval Response
{
  "id": "661982d8e1ee8192595fed2145490e13",
  "wallet": "654ec786c07fe8dc0dcfe03916ec5bb0",
  "enterprise": "62c5ae8174ac860007aff138a2d74df7",
  "bitgoOrg": "BitGo Trust",
  "creator": "62ab90e06dfda30007974f0a52a12995",
  "createDate": "2024-04-12T18:52:08.072Z",
  "approvedDate": "2024-04-12T18:58:29.774Z",
  "info": {
    "type": "genericRequest",
    "genericRequest": {
      "description": "Request to create policy rule {policyRuleId}",
      "anchors": [
        {
          "key": "policyRuleId",
          "value": "835c75f8-49e2-4d5b-82f0-0c8829d52a05",
          "anchorType": "policyRuleId"
        }
      ],
      "proposedId": "835c75f8-49e2-4d5b-82f0-0c8829d52a05",
      "resourceType": "policyRule",
      "changeType": "create",
      "metadata": {
        "sharedId": "5e43e1b6-665d-4406-b59a-b9e1d2e9dfad",
        "policyRuleName": "Spending limit - require approval on withdrawals of more than 100 USD"
      }
    }
  },
  "approvers": [],
  "state": "approved",
  "scope": "wallet",
  "userIds": [
    "62ab90e06dfda30007974f0a52a12995",
    "621d08a634ad8a0007fcddffd7c429cc",
    "627ff9325a5c1b0007c05a40d15e1522"
  ],
  "approvalsRequired": 1,
  "singleRunResults": [],
  "resolvers": [
    {
      "user": "627ff9325a5c1b0007c05a40d15e1522",
      "date": "2024-04-12T18:58:29.655Z",
      "resolutionType": "pending",
      "resolutionAction": "approve"
    }
  ],
  "policyEvaluationId": "57cd4e69-8038-4568-8124-55ca80ff94c1",
  "actions": [
    {
      "id": "65a52063-df3b-4362-bfc1-68d4e8b2cc6f",
      "status": "COMPLETE",
      "name": "approvals.customer.walletAdmin",
      "parameters": { "userIds": [] },
      "resolvers": [
        {
          "user": "627ff9325a5c1b0007c05a40d15e1522",
          "date": "2024-04-12T18:58:29.655Z",
          "resolutionType": "pending",
          "resolutionAction": "approve"
        }
      ],
      "approvers": ["621d08a634ad8a0007fcddffd7c429cc"]
    }
  ],
  "resolutionOrder": [{ "actions": ["65a52063-df3b-4362-bfc1-68d4e8b2cc6f"] }]
}